Git Overview

Git utilities for CodeMap.

DiffChunk dataclass

Represents a logical chunk of changes.

Source code in src/codemap/git/diff_splitter/schemas.py

@dataclass
class DiffChunk:
	"""Represents a logical chunk of changes."""

	files: list[str]
	content: str
	description: str | None = None
	is_llm_generated: bool = False
	filtered_files: list[str] | None = None

	def __post_init__(self) -> None:
		"""Initialize default values."""
		if self.filtered_files is None:
			self.filtered_files = []

	def __hash__(self) -> int:
		"""
		Make DiffChunk hashable by using the object's id.

		Returns:
		        Hash value based on the object's id

		"""
		return hash(id(self))

	def __eq__(self, other: object) -> bool:
		"""
		Compare DiffChunk objects for equality.

		Args:
		        other: Another object to compare with

		Returns:
		        True if the objects are the same instance, False otherwise

		"""
		if not isinstance(other, DiffChunk):
			return False
		return id(self) == id(other)

files instance-attribute

files: list[str]

content instance-attribute

content: str

description class-attribute instance-attribute

description: str | None = None

is_llm_generated class-attribute instance-attribute

is_llm_generated: bool = False

filtered_files class-attribute instance-attribute

filtered_files: list[str] | None = None

__post_init__

__post_init__() -> None

Initialize default values.

Source code in src/codemap/git/diff_splitter/schemas.py

def __post_init__(self) -> None:
	"""Initialize default values."""
	if self.filtered_files is None:
		self.filtered_files = []

__hash__

__hash__() -> int

Make DiffChunk hashable by using the object's id.

Returns:

Type	Description
int	Hash value based on the object's id

Source code in src/codemap/git/diff_splitter/schemas.py

def __hash__(self) -> int:
	"""
	Make DiffChunk hashable by using the object's id.

	Returns:
	        Hash value based on the object's id

	"""
	return hash(id(self))

__eq__

__eq__(other: object) -> bool

Compare DiffChunk objects for equality.

Parameters:

Name	Type	Description	Default
other	object	Another object to compare with	required

Returns:

Type	Description
bool	True if the objects are the same instance, False otherwise

Source code in src/codemap/git/diff_splitter/schemas.py

def __eq__(self, other: object) -> bool:
	"""
	Compare DiffChunk objects for equality.

	Args:
	        other: Another object to compare with

	Returns:
	        True if the objects are the same instance, False otherwise

	"""
	if not isinstance(other, DiffChunk):
		return False
	return id(self) == id(other)

__init__

__init__(
	files: list[str],
	content: str,
	description: str | None = None,
	is_llm_generated: bool = False,
	filtered_files: list[str] | None = None,
) -> None

DiffSplitter

Splits Git diffs into logical chunks.

Source code in src/codemap/git/diff_splitter/splitter.py

class DiffSplitter:
	"""Splits Git diffs into logical chunks."""

	# Class-level cache for the embedding model
	_embedding_model = None
	# Track availability of sentence-transformers and the model
	_sentence_transformers_available = None
	_model_available = None

	def __init__(
		self,
		repo_root: Path,
		# Defaults are now sourced from DEFAULT_CONFIG
		similarity_threshold: float = DEFAULT_CONFIG["commit"]["diff_splitter"]["similarity_threshold"],
		directory_similarity_threshold: float = DEFAULT_CONFIG["commit"]["diff_splitter"][
			"directory_similarity_threshold"
		],
		min_chunks_for_consolidation: int = DEFAULT_CONFIG["commit"]["diff_splitter"]["min_chunks_for_consolidation"],
		max_chunks_before_consolidation: int = DEFAULT_CONFIG["commit"]["diff_splitter"][
			"max_chunks_before_consolidation"
		],
		max_file_size_for_llm: int = DEFAULT_CONFIG["commit"]["diff_splitter"]["max_file_size_for_llm"],
		max_log_diff_size: int = DEFAULT_CONFIG["commit"]["diff_splitter"]["max_log_diff_size"],
		model_name: str = DEFAULT_CONFIG["commit"]["diff_splitter"]["model_name"],
	) -> None:
		"""
		Initialize the diff splitter.

		Args:
		    repo_root: Root directory of the Git repository
		    similarity_threshold: Threshold for grouping by content similarity.
		    directory_similarity_threshold: Threshold for directory similarity.
		    min_chunks_for_consolidation: Min chunks to trigger consolidation.
		    max_chunks_before_consolidation: Max chunks allowed before forced consolidation.
		    max_file_size_for_llm: Max file size (bytes) to process for LLM context.
		        Defaults to value from `DEFAULT_CONFIG["commit"]["diff_splitter"]["max_file_size_for_llm"]` if None.
		    max_log_diff_size: Max diff size (bytes) to log in debug mode.
		        Defaults to value from `DEFAULT_CONFIG["commit"]["diff_splitter"]["max_log_diff_size"]` if None.
		    model_name: Name of the sentence-transformer model to use.
		        Defaults to value from `DEFAULT_CONFIG["commit"]["diff_splitter"]["model_name"]` if None.

		"""
		self.repo_root = repo_root
		# Store thresholds
		self.similarity_threshold = similarity_threshold
		self.directory_similarity_threshold = directory_similarity_threshold
		self.min_chunks_for_consolidation = min_chunks_for_consolidation
		self.max_chunks_before_consolidation = max_chunks_before_consolidation
		# Store other settings
		self.max_file_size_for_llm = max_file_size_for_llm
		self.max_log_diff_size = max_log_diff_size
		self.model_name = model_name

		# Do NOT automatically check availability - let the command class do this explicitly
		# This avoids checks happening during initialization without visible loading states

	@classmethod
	def _check_sentence_transformers_availability(cls) -> bool:
		"""
		Check if sentence-transformers package is available.

		Returns:
		    True if sentence-transformers is available, False otherwise

		"""
		try:
			# This is needed for the import check, but don't flag as unused
			import sentence_transformers  # type: ignore  # noqa: F401, PGH003

			# Set the class flag for future reference
			cls._sentence_transformers_available = True
			logger.debug("sentence-transformers is available")
			return True
		except ImportError as e:
			# Log the specific import error for better debugging
			cls._sentence_transformers_available = False
			logger.warning(
				"sentence-transformers import failed: %s. Semantic similarity features will be limited. "
				"Install with: pip install sentence-transformers numpy",
				e,
			)
			return False
		except (RuntimeError, ValueError, AttributeError) as e:
			# Catch specific errors during import
			cls._sentence_transformers_available = False
			logger.warning(
				"Unexpected error importing sentence-transformers: %s. Semantic similarity features will be limited.", e
			)
			return False

	@classmethod
	def are_sentence_transformers_available(cls) -> bool:
		"""
		Check if sentence transformers are available.

		Returns:
		    True if sentence transformers are available, False otherwise

		"""
		return cls._sentence_transformers_available or cls._check_sentence_transformers_availability()

	@classmethod
	def is_model_available(cls) -> bool:
		"""
		Check if embedding model is available.

		Returns:
		    True if embedding model is available, False otherwise

		"""
		return bool(cls._model_available)

	@classmethod
	def set_model_available(cls, value: bool) -> None:
		"""
		Set model availability flag.

		Args:
		    value: Boolean indicating if model is available

		"""
		cls._model_available = value

	@classmethod
	def get_embedding_model(cls) -> EmbeddingModel | None:
		"""
		Get the embedding model.

		Returns:
		    The embedding model or None if not available

		"""
		return cls._embedding_model

	@classmethod
	def set_embedding_model(cls, model: EmbeddingModel) -> None:
		"""
		Set the embedding model.

		Args:
		    model: The embedding model to set

		"""
		cls._embedding_model = model

	def _check_model_availability(self) -> bool:
		"""
		Check if the embedding model is available using the instance's configured model name.

		Returns:
		    True if model is available, False otherwise

		"""
		# Use class method to access class-level cache check
		if not self.__class__.are_sentence_transformers_available():
			return False

		try:
			from sentence_transformers import SentenceTransformer

			# Use class method to access class-level cache
			if self.__class__.get_embedding_model() is None:
				# Use self.model_name from instance configuration
				logger.debug("Loading embedding model: %s", self.model_name)

				try:
					console.print("Loading embedding model...")
					# Load the model using self.model_name
					model = SentenceTransformer(self.model_name)
					self.__class__.set_embedding_model(cast("EmbeddingModel", model))
					console.print("[green]✓[/green] Model loaded successfully")
					logger.debug("Initialized embedding model: %s", self.model_name)
					# Set class-level flag via class method
					self.__class__.set_model_available(True)
					return True
				except ImportError as e:
					logger.exception("Missing dependencies for embedding model")
					console.print(f"[red]Error: Missing dependencies: {e}[/red]")
					self.__class__.set_model_available(False)
					return False
				except MemoryError:
					logger.exception("Not enough memory to load embedding model")
					console.print("[red]Error: Not enough memory to load embedding model[/red]")
					self.__class__.set_model_available(False)
					return False
				except ValueError as e:
					logger.exception("Invalid model configuration")
					console.print(f"[red]Error: Invalid model configuration: {e}[/red]")
					self.__class__.set_model_available(False)
					return False
				except RuntimeError as e:
					error_msg = str(e)
					# Check for CUDA/GPU related errors
					if "CUDA" in error_msg or "GPU" in error_msg:
						logger.exception("GPU error when loading model")
						console.print("[red]Error: GPU/CUDA error. Try using CPU only mode.[/red]")
					else:
						logger.exception("Runtime error when loading model")
						console.print(f"[red]Error loading model: {error_msg}[/red]")
					self.__class__.set_model_available(False)
					return False
				except Exception as e:
					logger.exception("Unexpected error loading embedding model")
					console.print(f"[red]Unexpected error loading model: {e}[/red]")
					self.__class__.set_model_available(False)
					return False
			# If we already have a model loaded, make sure to set the flag to True
			self.__class__.set_model_available(True)
			return True
		except Exception as e:
			# This is the outer exception handler for any unexpected errors
			logger.exception("Failed to load embedding model %s", self.model_name)
			console.print(f"[red]Failed to load embedding model: {e}[/red]")
			self.__class__.set_model_available(False)
			return False

	def split_diff(self, diff: GitDiff) -> tuple[list[DiffChunk], list[str]]:
		"""
		Split a diff into logical chunks using semantic splitting.

		Args:
		    diff: GitDiff object to split

		Returns:
		    Tuple of (List of DiffChunk objects based on semantic analysis, List of filtered large files)

		Raises:
		    ValueError: If semantic splitting is not available or fails

		"""
		if not diff.files:
			return [], []

		# Special handling for untracked files - bypass semantic split since the content isn't a proper diff format
		if diff.is_untracked:
			logger.debug("Processing untracked files with special handling: %d files", len(diff.files))
			# Create a simple chunk per file to avoid errors with unidiff parsing
			chunks = []
			for file_path in diff.files:
				# Create a basic chunk with file info but without trying to parse the content as a diff
				chunks = [
					DiffChunk(
						files=[file_path],
						content=f"New untracked file: {file_path}",
						description=f"New file: {file_path}",
					)
					for file_path in diff.files
				]
			return chunks, []

		# In test environments, log the diff content for debugging
		if is_test_environment():
			logger.debug("Processing diff in test environment with %d files", len(diff.files) if diff.files else 0)
			if diff.content and len(diff.content) < self.max_log_diff_size:  # Use configured max log size
				logger.debug("Diff content: %s", diff.content)

		# Process files in the diff
		if diff.files:
			# Filter for valid files (existence, tracked status), max_size check removed here
			diff.files, _ = filter_valid_files(diff.files, is_test_environment())
			# filtered_large_files list is no longer populated or used here

		if not diff.files:
			logger.warning("No valid files to process after filtering")
			return [], []  # Return empty lists

		# Set up availability flags if not already set
		# Use class method to check sentence transformers availability
		if not self.__class__.are_sentence_transformers_available():
			msg = (
				"Semantic splitting is not available. sentence-transformers package is required. "
				"Install with: pip install sentence-transformers numpy"
			)
			raise ValueError(msg)

		# Try to load the model using the instance method
		with loading_spinner("Loading embedding model..."):
			# Use self._check_model_availability() - it uses self.model_name internally
			if not self.__class__.is_model_available():
				self._check_model_availability()

		if not self.__class__.is_model_available():
			msg = "Semantic splitting failed: embedding model could not be loaded. Check logs for details."
			raise ValueError(msg)

		try:
			chunks = self._split_semantic(diff)

			# If we truncated the content, restore the original content for the actual chunks
			if diff.content and chunks:
				# Create a mapping of file paths to chunks for quick lookup
				chunks_by_file = {}
				for chunk in chunks:
					for file_path in chunk.files:
						if file_path not in chunks_by_file:
							chunks_by_file[file_path] = []
						chunks_by_file[file_path].append(chunk)

				# For chunks that represent files we can find in the original content,
				# update their content to include the full original diff for that file
				for chunk in chunks:
					# Use a heuristic to match file sections in the original content
					for file_path in chunk.files:
						file_marker = f"diff --git a/{file_path} b/{file_path}"
						if file_marker in diff.content:
							# Found a match for this file in the original content
							# Extract that file's complete diff section
							start_idx = diff.content.find(file_marker)
							end_idx = diff.content.find("diff --git", start_idx + len(file_marker))
							if end_idx == -1:  # Last file in the diff
								end_idx = len(diff.content)

							file_diff = diff.content[start_idx:end_idx].strip()

							# Now replace just this file's content in the chunk
							# This is a heuristic that may need adjustment based on your diff format
							if chunk.content and file_marker in chunk.content:
								chunk_start = chunk.content.find(file_marker)
								chunk_end = chunk.content.find("diff --git", chunk_start + len(file_marker))
								if chunk_end == -1:  # Last file in the chunk
									chunk_end = len(chunk.content)

								# Replace this file's truncated diff with the full diff
								chunk.content = chunk.content[:chunk_start] + file_diff + chunk.content[chunk_end:]

			return chunks, []
		except Exception as e:
			logger.exception("Semantic splitting failed")
			console.print(f"[red]Semantic splitting failed: {e}[/red]")

			# Try basic splitting as a fallback
			logger.warning("Falling back to basic file splitting")
			console.print("[yellow]Falling back to basic file splitting[/yellow]")
			# Return empty list for filtered_large_files as it's no longer tracked here
			return self._create_basic_file_chunk(diff), []

	def _create_basic_file_chunk(self, diff: GitDiff) -> list[DiffChunk]:
		"""
		Create a basic chunk per file without semantic analysis.

		Args:
		    diff: GitDiff object to split

		Returns:
		    List of DiffChunk objects, one per file

		"""
		chunks = []

		if diff.files:
			# Create a basic chunk, one per file in this strategy, no semantic grouping
			strategy = FileSplitStrategy()
			chunks = strategy.split(diff)

		return chunks

	def _split_semantic(self, diff: GitDiff) -> list[DiffChunk]:
		"""
		Perform semantic splitting, falling back if needed.

		Args:
		    diff: GitDiff object to split

		Returns:
		    List of DiffChunk objects

		Raises:
		    ValueError: If semantic splitting fails and fallback is not possible.

		"""
		if not self.are_sentence_transformers_available():
			logger.warning("Sentence transformers unavailable. Falling back to file-based splitting.")
			# Directly use FileSplitStrategy when ST is unavailable
			file_splitter = FileSplitStrategy()
			return file_splitter.split(diff)

		# Existing logic for semantic splitting when ST is available
		try:
			semantic_strategy = SemanticSplitStrategy(embedding_model=self._embedding_model)
			return semantic_strategy.split(diff)
		except Exception:
			logger.exception("Semantic splitting failed: %s. Falling back to file splitting.")
			# Fallback to FileSplitStrategy on any semantic splitting error
			file_splitter = FileSplitStrategy()
			return file_splitter.split(diff)

	def _calculate_semantic_similarity(self, text1: str, text2: str) -> float:
		"""
		Calculate semantic similarity between two texts using the embedding model.

		Args:
		    text1: First text
		    text2: Second text

		Returns:
		    Similarity score between 0 and 1

		"""
		# Check if embedding model is available
		if not self.__class__.are_sentence_transformers_available():
			logger.debug("Sentence transformers not available, returning zero similarity")
			return 0.0

		# Call instance method self._check_model_availability()
		if not self.__class__.is_model_available():
			self._check_model_availability()

		if not self.__class__.is_model_available() or self.__class__.get_embedding_model() is None:
			logger.debug("Embedding model not available, returning zero similarity")
			return 0.0

		# Assign to local variable after check guarantees it's not None
		embedding_model_maybe_none = self.__class__.get_embedding_model()
		if embedding_model_maybe_none is None:
			# This case should have been caught earlier, but log just in case
			logger.error("Embedding model unexpectedly None after availability check")
			return 0.0

		embedding_model = embedding_model_maybe_none  # Now we know it's not None

		try:
			# Get embeddings for both texts
			emb1 = embedding_model.encode([text1])[0]
			emb2 = embedding_model.encode([text2])[0]

			# Calculate similarity using numpy
			return calculate_semantic_similarity(emb1.tolist(), emb2.tolist())
		except (ValueError, TypeError, IndexError, RuntimeError) as e:
			logger.warning("Failed to calculate semantic similarity: %s", e)
			return 0.0

	def encode_chunks(self, chunks: list[str]) -> dict[str, np.ndarray]:
		"""
		Encode a list of text chunks using the embedding model.

		Args:
		    chunks: List of text chunks to encode

		Returns:
		    Dictionary with embeddings array

		"""
		# Ensure the model is initialized
		if self.__class__.are_sentence_transformers_available() and not self.__class__.is_model_available():
			self._check_model_availability()

		if not self.__class__.is_model_available():
			logger.debug("Embedding model not available, returning empty embeddings")
			return {"embeddings": np.array([])}

		# Skip empty chunks
		if not chunks:
			logger.debug("No chunks to encode")
			return {"embeddings": np.array([])}

		# Use class method for class cache access
		if self.__class__.get_embedding_model() is None:
			logger.debug("Embedding model is None but was marked as available, reinitializing")
			# Re-check availability using instance method
			self._check_model_availability()

		# Check again after potential re-initialization and assign to local variable
		if self.__class__.get_embedding_model() is None:
			logger.error("Embedding model is still None after re-check")
			return {"embeddings": np.array([])}

		# Explicitly cast after the check
		embedding_model_maybe_none = self.__class__.get_embedding_model()
		if embedding_model_maybe_none is None:
			logger.error("Embedding model unexpectedly None in encode_chunks")
			return {"embeddings": np.array([])}

		embedding_model = embedding_model_maybe_none  # Now we know it's not None

		try:
			logger.debug("Encoding %d chunks", len(chunks))
			embeddings = embedding_model.encode(chunks)
			logger.debug("Successfully encoded %d chunks to shape %s", len(chunks), embeddings.shape)
			return {"embeddings": embeddings}
		except Exception:
			logger.exception("Error encoding chunks")
			return {"embeddings": np.array([])}  # Return empty on error

__init__

__init__(
	repo_root: Path,
	similarity_threshold: float = DEFAULT_CONFIG["commit"][
		"diff_splitter"
	]["similarity_threshold"],
	directory_similarity_threshold: float = DEFAULT_CONFIG[
		"commit"
	]["diff_splitter"]["directory_similarity_threshold"],
	min_chunks_for_consolidation: int = DEFAULT_CONFIG[
		"commit"
	]["diff_splitter"]["min_chunks_for_consolidation"],
	max_chunks_before_consolidation: int = DEFAULT_CONFIG[
		"commit"
	]["diff_splitter"]["max_chunks_before_consolidation"],
	max_file_size_for_llm: int = DEFAULT_CONFIG["commit"][
		"diff_splitter"
	]["max_file_size_for_llm"],
	max_log_diff_size: int = DEFAULT_CONFIG["commit"][
		"diff_splitter"
	]["max_log_diff_size"],
	model_name: str = DEFAULT_CONFIG["commit"][
		"diff_splitter"
	]["model_name"],
) -> None

Initialize the diff splitter.

Parameters:

Name	Type	Description	Default
repo_root	Path	Root directory of the Git repository	required
similarity_threshold	float	Threshold for grouping by content similarity.	DEFAULT_CONFIG['commit']['diff_splitter']['similarity_threshold']
directory_similarity_threshold	float	Threshold for directory similarity.	DEFAULT_CONFIG['commit']['diff_splitter']['directory_similarity_threshold']
min_chunks_for_consolidation	int	Min chunks to trigger consolidation.	DEFAULT_CONFIG['commit']['diff_splitter']['min_chunks_for_consolidation']
max_chunks_before_consolidation	int	Max chunks allowed before forced consolidation.	DEFAULT_CONFIG['commit']['diff_splitter']['max_chunks_before_consolidation']
max_file_size_for_llm	int	Max file size (bytes) to process for LLM context. Defaults to value from DEFAULT_CONFIG["commit"]["diff_splitter"]["max_file_size_for_llm"] if None.	DEFAULT_CONFIG['commit']['diff_splitter']['max_file_size_for_llm']
max_log_diff_size	int	Max diff size (bytes) to log in debug mode. Defaults to value from DEFAULT_CONFIG["commit"]["diff_splitter"]["max_log_diff_size"] if None.	DEFAULT_CONFIG['commit']['diff_splitter']['max_log_diff_size']
model_name	str	Name of the sentence-transformer model to use. Defaults to value from DEFAULT_CONFIG["commit"]["diff_splitter"]["model_name"] if None.	DEFAULT_CONFIG['commit']['diff_splitter']['model_name']

Source code in src/codemap/git/diff_splitter/splitter.py

def __init__(
	self,
	repo_root: Path,
	# Defaults are now sourced from DEFAULT_CONFIG
	similarity_threshold: float = DEFAULT_CONFIG["commit"]["diff_splitter"]["similarity_threshold"],
	directory_similarity_threshold: float = DEFAULT_CONFIG["commit"]["diff_splitter"][
		"directory_similarity_threshold"
	],
	min_chunks_for_consolidation: int = DEFAULT_CONFIG["commit"]["diff_splitter"]["min_chunks_for_consolidation"],
	max_chunks_before_consolidation: int = DEFAULT_CONFIG["commit"]["diff_splitter"][
		"max_chunks_before_consolidation"
	],
	max_file_size_for_llm: int = DEFAULT_CONFIG["commit"]["diff_splitter"]["max_file_size_for_llm"],
	max_log_diff_size: int = DEFAULT_CONFIG["commit"]["diff_splitter"]["max_log_diff_size"],
	model_name: str = DEFAULT_CONFIG["commit"]["diff_splitter"]["model_name"],
) -> None:
	"""
	Initialize the diff splitter.

	Args:
	    repo_root: Root directory of the Git repository
	    similarity_threshold: Threshold for grouping by content similarity.
	    directory_similarity_threshold: Threshold for directory similarity.
	    min_chunks_for_consolidation: Min chunks to trigger consolidation.
	    max_chunks_before_consolidation: Max chunks allowed before forced consolidation.
	    max_file_size_for_llm: Max file size (bytes) to process for LLM context.
	        Defaults to value from `DEFAULT_CONFIG["commit"]["diff_splitter"]["max_file_size_for_llm"]` if None.
	    max_log_diff_size: Max diff size (bytes) to log in debug mode.
	        Defaults to value from `DEFAULT_CONFIG["commit"]["diff_splitter"]["max_log_diff_size"]` if None.
	    model_name: Name of the sentence-transformer model to use.
	        Defaults to value from `DEFAULT_CONFIG["commit"]["diff_splitter"]["model_name"]` if None.

	"""
	self.repo_root = repo_root
	# Store thresholds
	self.similarity_threshold = similarity_threshold
	self.directory_similarity_threshold = directory_similarity_threshold
	self.min_chunks_for_consolidation = min_chunks_for_consolidation
	self.max_chunks_before_consolidation = max_chunks_before_consolidation
	# Store other settings
	self.max_file_size_for_llm = max_file_size_for_llm
	self.max_log_diff_size = max_log_diff_size
	self.model_name = model_name

repo_root instance-attribute

repo_root = repo_root

similarity_threshold instance-attribute

similarity_threshold = similarity_threshold

directory_similarity_threshold instance-attribute

directory_similarity_threshold = (
	directory_similarity_threshold
)

min_chunks_for_consolidation instance-attribute

min_chunks_for_consolidation = min_chunks_for_consolidation

max_chunks_before_consolidation instance-attribute

max_chunks_before_consolidation = (
	max_chunks_before_consolidation
)

max_file_size_for_llm instance-attribute

max_file_size_for_llm = max_file_size_for_llm

max_log_diff_size instance-attribute

max_log_diff_size = max_log_diff_size

model_name instance-attribute

model_name = model_name

are_sentence_transformers_available classmethod

are_sentence_transformers_available() -> bool

Check if sentence transformers are available.

Returns:

Type	Description
bool	True if sentence transformers are available, False otherwise

Source code in src/codemap/git/diff_splitter/splitter.py

@classmethod
def are_sentence_transformers_available(cls) -> bool:
	"""
	Check if sentence transformers are available.

	Returns:
	    True if sentence transformers are available, False otherwise

	"""
	return cls._sentence_transformers_available or cls._check_sentence_transformers_availability()

is_model_available classmethod

is_model_available() -> bool

Check if embedding model is available.

Returns:

Type	Description
bool	True if embedding model is available, False otherwise

Source code in src/codemap/git/diff_splitter/splitter.py

@classmethod
def is_model_available(cls) -> bool:
	"""
	Check if embedding model is available.

	Returns:
	    True if embedding model is available, False otherwise

	"""
	return bool(cls._model_available)

set_model_available classmethod

set_model_available(value: bool) -> None

Set model availability flag.

Parameters:

Name	Type	Description	Default
value	bool	Boolean indicating if model is available	required

Source code in src/codemap/git/diff_splitter/splitter.py

@classmethod
def set_model_available(cls, value: bool) -> None:
	"""
	Set model availability flag.

	Args:
	    value: Boolean indicating if model is available

	"""
	cls._model_available = value

get_embedding_model classmethod

get_embedding_model() -> EmbeddingModel | None

Get the embedding model.

Returns:

Type	Description
EmbeddingModel | None	The embedding model or None if not available

Source code in src/codemap/git/diff_splitter/splitter.py

@classmethod
def get_embedding_model(cls) -> EmbeddingModel | None:
	"""
	Get the embedding model.

	Returns:
	    The embedding model or None if not available

	"""
	return cls._embedding_model

set_embedding_model classmethod

set_embedding_model(model: EmbeddingModel) -> None

Set the embedding model.

Parameters:

Name	Type	Description	Default
model	EmbeddingModel	The embedding model to set	required

Source code in src/codemap/git/diff_splitter/splitter.py

@classmethod
def set_embedding_model(cls, model: EmbeddingModel) -> None:
	"""
	Set the embedding model.

	Args:
	    model: The embedding model to set

	"""
	cls._embedding_model = model

split_diff

split_diff(
	diff: GitDiff,
) -> tuple[list[DiffChunk], list[str]]

Split a diff into logical chunks using semantic splitting.

Parameters:

Name	Type	Description	Default
diff	GitDiff	GitDiff object to split	required

Returns:

Type	Description
tuple[list[DiffChunk], list[str]]	Tuple of (List of DiffChunk objects based on semantic analysis, List of filtered large files)

Raises:

Type	Description
ValueError	If semantic splitting is not available or fails

Source code in src/codemap/git/diff_splitter/splitter.py

def split_diff(self, diff: GitDiff) -> tuple[list[DiffChunk], list[str]]:
	"""
	Split a diff into logical chunks using semantic splitting.

	Args:
	    diff: GitDiff object to split

	Returns:
	    Tuple of (List of DiffChunk objects based on semantic analysis, List of filtered large files)

	Raises:
	    ValueError: If semantic splitting is not available or fails

	"""
	if not diff.files:
		return [], []

	# Special handling for untracked files - bypass semantic split since the content isn't a proper diff format
	if diff.is_untracked:
		logger.debug("Processing untracked files with special handling: %d files", len(diff.files))
		# Create a simple chunk per file to avoid errors with unidiff parsing
		chunks = []
		for file_path in diff.files:
			# Create a basic chunk with file info but without trying to parse the content as a diff
			chunks = [
				DiffChunk(
					files=[file_path],
					content=f"New untracked file: {file_path}",
					description=f"New file: {file_path}",
				)
				for file_path in diff.files
			]
		return chunks, []

	# In test environments, log the diff content for debugging
	if is_test_environment():
		logger.debug("Processing diff in test environment with %d files", len(diff.files) if diff.files else 0)
		if diff.content and len(diff.content) < self.max_log_diff_size:  # Use configured max log size
			logger.debug("Diff content: %s", diff.content)

	# Process files in the diff
	if diff.files:
		# Filter for valid files (existence, tracked status), max_size check removed here
		diff.files, _ = filter_valid_files(diff.files, is_test_environment())
		# filtered_large_files list is no longer populated or used here

	if not diff.files:
		logger.warning("No valid files to process after filtering")
		return [], []  # Return empty lists

	# Set up availability flags if not already set
	# Use class method to check sentence transformers availability
	if not self.__class__.are_sentence_transformers_available():
		msg = (
			"Semantic splitting is not available. sentence-transformers package is required. "
			"Install with: pip install sentence-transformers numpy"
		)
		raise ValueError(msg)

	# Try to load the model using the instance method
	with loading_spinner("Loading embedding model..."):
		# Use self._check_model_availability() - it uses self.model_name internally
		if not self.__class__.is_model_available():
			self._check_model_availability()

	if not self.__class__.is_model_available():
		msg = "Semantic splitting failed: embedding model could not be loaded. Check logs for details."
		raise ValueError(msg)

	try:
		chunks = self._split_semantic(diff)

		# If we truncated the content, restore the original content for the actual chunks
		if diff.content and chunks:
			# Create a mapping of file paths to chunks for quick lookup
			chunks_by_file = {}
			for chunk in chunks:
				for file_path in chunk.files:
					if file_path not in chunks_by_file:
						chunks_by_file[file_path] = []
					chunks_by_file[file_path].append(chunk)

			# For chunks that represent files we can find in the original content,
			# update their content to include the full original diff for that file
			for chunk in chunks:
				# Use a heuristic to match file sections in the original content
				for file_path in chunk.files:
					file_marker = f"diff --git a/{file_path} b/{file_path}"
					if file_marker in diff.content:
						# Found a match for this file in the original content
						# Extract that file's complete diff section
						start_idx = diff.content.find(file_marker)
						end_idx = diff.content.find("diff --git", start_idx + len(file_marker))
						if end_idx == -1:  # Last file in the diff
							end_idx = len(diff.content)

						file_diff = diff.content[start_idx:end_idx].strip()

						# Now replace just this file's content in the chunk
						# This is a heuristic that may need adjustment based on your diff format
						if chunk.content and file_marker in chunk.content:
							chunk_start = chunk.content.find(file_marker)
							chunk_end = chunk.content.find("diff --git", chunk_start + len(file_marker))
							if chunk_end == -1:  # Last file in the chunk
								chunk_end = len(chunk.content)

							# Replace this file's truncated diff with the full diff
							chunk.content = chunk.content[:chunk_start] + file_diff + chunk.content[chunk_end:]

		return chunks, []
	except Exception as e:
		logger.exception("Semantic splitting failed")
		console.print(f"[red]Semantic splitting failed: {e}[/red]")

		# Try basic splitting as a fallback
		logger.warning("Falling back to basic file splitting")
		console.print("[yellow]Falling back to basic file splitting[/yellow]")
		# Return empty list for filtered_large_files as it's no longer tracked here
		return self._create_basic_file_chunk(diff), []

encode_chunks

encode_chunks(chunks: list[str]) -> dict[str, ndarray]

Encode a list of text chunks using the embedding model.

Parameters:

Name	Type	Description	Default
chunks	list[str]	List of text chunks to encode	required

Returns:

Type	Description
dict[str, ndarray]	Dictionary with embeddings array

Source code in src/codemap/git/diff_splitter/splitter.py

def encode_chunks(self, chunks: list[str]) -> dict[str, np.ndarray]:
	"""
	Encode a list of text chunks using the embedding model.

	Args:
	    chunks: List of text chunks to encode

	Returns:
	    Dictionary with embeddings array

	"""
	# Ensure the model is initialized
	if self.__class__.are_sentence_transformers_available() and not self.__class__.is_model_available():
		self._check_model_availability()

	if not self.__class__.is_model_available():
		logger.debug("Embedding model not available, returning empty embeddings")
		return {"embeddings": np.array([])}

	# Skip empty chunks
	if not chunks:
		logger.debug("No chunks to encode")
		return {"embeddings": np.array([])}

	# Use class method for class cache access
	if self.__class__.get_embedding_model() is None:
		logger.debug("Embedding model is None but was marked as available, reinitializing")
		# Re-check availability using instance method
		self._check_model_availability()

	# Check again after potential re-initialization and assign to local variable
	if self.__class__.get_embedding_model() is None:
		logger.error("Embedding model is still None after re-check")
		return {"embeddings": np.array([])}

	# Explicitly cast after the check
	embedding_model_maybe_none = self.__class__.get_embedding_model()
	if embedding_model_maybe_none is None:
		logger.error("Embedding model unexpectedly None in encode_chunks")
		return {"embeddings": np.array([])}

	embedding_model = embedding_model_maybe_none  # Now we know it's not None

	try:
		logger.debug("Encoding %d chunks", len(chunks))
		embeddings = embedding_model.encode(chunks)
		logger.debug("Successfully encoded %d chunks to shape %s", len(chunks), embeddings.shape)
		return {"embeddings": embeddings}
	except Exception:
		logger.exception("Error encoding chunks")
		return {"embeddings": np.array([])}  # Return empty on error

GitDiff dataclass

Represents a Git diff chunk.

Source code in src/codemap/git/utils.py

@dataclass
class GitDiff:
	"""Represents a Git diff chunk."""

	files: list[str]
	content: str
	is_staged: bool = False
	is_untracked: bool = False

files instance-attribute

files: list[str]

content instance-attribute

content: str

is_staged class-attribute instance-attribute

is_staged: bool = False

is_untracked class-attribute instance-attribute

is_untracked: bool = False

__init__

__init__(
	files: list[str],
	content: str,
	is_staged: bool = False,
	is_untracked: bool = False,
) -> None

GitError

Bases: Exception

Custom exception for Git-related errors.

Source code in src/codemap/git/utils.py

class GitError(Exception):
	"""Custom exception for Git-related errors."""

run_git_command

run_git_command(
	command: list[str],
	cwd: Path | str | None = None,
	environment: dict[str, str] | None = None,
) -> str

Run a git command and return its output.

Parameters:

Name	Type	Description	Default
command	list[str]	Command to run as a list of string arguments	required
cwd	Path | str | None	Working directory to run the command in	None
environment	dict[str, str] | None	Environment variables to use	None

Returns:

Type	Description
str	The output from the command

Raises:

Type	Description
GitError	If the git command fails

Source code in src/codemap/git/utils.py

def run_git_command(
	command: list[str],
	cwd: Path | str | None = None,
	environment: dict[str, str] | None = None,
) -> str:
	"""
	Run a git command and return its output.

	Args:
	    command: Command to run as a list of string arguments
	    cwd: Working directory to run the command in
	    environment: Environment variables to use

	Returns:
	    The output from the command

	Raises:
	    GitError: If the git command fails

	"""
	try:
		# Using subprocess.run with a list of arguments is safe since we're not using shell=True
		# and the command is not being built from untrusted input
		result = subprocess.run(  # noqa: S603
			command,
			cwd=cwd,
			capture_output=True,
			text=True,
			check=True,
			env=environment,
		)
		return result.stdout.strip()
	except subprocess.CalledProcessError as e:
		# Check if this is a pre-commit hook failure for commit - handled specially by the UI
		if command and len(command) > 1 and command[1] == "commit":
			if "pre-commit" in (e.stderr or ""):
				# This is a pre-commit hook failure - which is handled by the UI, so don't log as exception
				logger.warning("Git hooks failed: %s", e.stderr)
				msg = f"{e.stderr}"
				raise GitError(msg) from e
			# Regular commit error
			logger.exception("Git command failed: %s", " ".join(command))

		cmd_str = " ".join(command)
		error_output = e.stderr or ""
		error_msg = f"Git command failed: {cmd_str}\n{error_output}"
		logger.exception(error_msg)
		raise GitError(error_output or error_msg) from e
	except Exception as e:
		error_msg = f"Error running git command: {e}"
		logger.exception(error_msg)
		raise GitError(error_msg) from e

interactive

Interactive commit interface for CodeMap.

logger module-attribute

logger = getLogger(__name__)

MAX_PREVIEW_LENGTH module-attribute

MAX_PREVIEW_LENGTH = 200

MAX_PREVIEW_LINES module-attribute

MAX_PREVIEW_LINES = 10

ChunkAction

Bases: Enum

Possible actions for a diff chunk.

Source code in src/codemap/git/interactive.py

class ChunkAction(Enum):
	"""Possible actions for a diff chunk."""

	COMMIT = auto()
	EDIT = auto()
	SKIP = auto()
	ABORT = auto()
	REGENERATE = auto()
	EXIT = auto()

COMMIT class-attribute instance-attribute

COMMIT = auto()

EDIT class-attribute instance-attribute

EDIT = auto()

SKIP class-attribute instance-attribute

SKIP = auto()

ABORT class-attribute instance-attribute

ABORT = auto()

REGENERATE class-attribute instance-attribute

REGENERATE = auto()

EXIT class-attribute instance-attribute

EXIT = auto()

ChunkResult dataclass

Result of processing a diff chunk.

Source code in src/codemap/git/interactive.py

@dataclass
class ChunkResult:
	"""Result of processing a diff chunk."""

	action: ChunkAction
	message: str | None = None

__init__

__init__(
	action: ChunkAction, message: str | None = None
) -> None

action instance-attribute

action: ChunkAction

message class-attribute instance-attribute

message: str | None = None

CommitUI

Interactive UI for the commit process.

Source code in src/codemap/git/interactive.py

class CommitUI:
	"""Interactive UI for the commit process."""

	def __init__(self) -> None:
		"""Initialize the commit UI."""
		self.console = Console()

	def display_chunk(self, chunk: DiffChunk, index: int = 0, total: int = 1) -> None:
		"""
		Display a diff chunk to the user.

		Args:
		    chunk: DiffChunk to display
		    index: The 0-based index of the current chunk
		    total: The total number of chunks

		"""
		# Build file information
		file_info = Text("Files: ", style="blue")
		file_info.append(", ".join(chunk.files))

		# Calculate changes
		added = len(
			[line for line in chunk.content.splitlines() if line.startswith("+") and not line.startswith("+++")]
		)
		removed = len(
			[line for line in chunk.content.splitlines() if line.startswith("-") and not line.startswith("---")]
		)
		changes_info = Text("\nChanges: ", style="blue")
		changes_info.append(f"{added} added, {removed} removed")

		# Prepare diff content
		panel_content = chunk.content
		if not panel_content.strip():
			panel_content = "No content diff available (e.g., new file or mode change)"

		# Truncate to maximum of MAX_PREVIEW_LINES lines
		content_lines = panel_content.splitlines()
		if len(content_lines) > MAX_PREVIEW_LINES:
			remaining_lines = len(content_lines) - MAX_PREVIEW_LINES
			panel_content = "\n".join(content_lines[:MAX_PREVIEW_LINES]) + f"\n... ({remaining_lines} more lines)"

		diff_content = Text("\n" + panel_content)

		# Determine title for the panel - use provided index and total
		panel_title = f"[bold]Commit {index + 1} of {total}[/bold]"

		# Create content for the panel conditionally
		if getattr(chunk, "description", None):
			# If there's a description, create a combined panel
			if getattr(chunk, "is_llm_generated", False):
				message_title = "[bold blue]Proposed message (AI)[/]"
				message_style = "blue"
			else:
				message_title = "[bold yellow]Proposed message (Simple)[/]"
				message_style = "yellow"

			# Create separate panels and print them
			# First, print the diff panel
			diff_panel = Panel(
				Group(file_info, changes_info, diff_content),
				title=panel_title,
				border_style="cyan",
				expand=True,
				width=self.console.width,
				padding=(1, 2),
			)
			self.console.print(diff_panel)

			# Print divider
			self.console.print(Rule(style="dim"))

			# Then print the message panel
			message_panel = Panel(
				Text(str(chunk.description), style="green"),
				title=message_title,
				border_style=message_style,
				expand=True,
				width=self.console.width,
				padding=(1, 2),
			)
			self.console.print(message_panel)
		else:
			# If no description, just print the diff panel
			panel = Panel(
				Group(file_info, changes_info, diff_content),
				title=panel_title,
				border_style="cyan",
				expand=True,
				width=self.console.width,
				padding=(1, 2),
			)
			self.console.print()
			self.console.print(panel)
			self.console.print()

	def display_group(self, group: SemanticGroup, index: int = 0, total: int = 1) -> None:
		"""
		Display a semantic group to the user.

		Args:
		        group: SemanticGroup to display
		        index: The 0-based index of the current group
		        total: The total number of groups

		"""
		# Build file information
		file_list = "\n".join([f"  - {file}" for file in group.files])
		file_info = Text(f"Files ({len(group.files)}):\n", style="blue")
		file_info.append(file_list)

		# Prepare diff preview - show first few lines of diff content
		diff_preview = group.content
		content_lines = diff_preview.splitlines()
		if len(content_lines) > MAX_PREVIEW_LINES:
			remaining_lines = len(content_lines) - MAX_PREVIEW_LINES
			diff_preview = "\n".join(content_lines[:MAX_PREVIEW_LINES]) + f"\n... ({remaining_lines} more lines)"
		diff_content = Text("\n\nDiff Preview:\n", style="blue")
		diff_content.append(diff_preview)

		# Calculate changes
		added = len(
			[line for line in group.content.splitlines() if line.startswith("+") and not line.startswith("+++")]
		)
		removed = len(
			[line for line in group.content.splitlines() if line.startswith("-") and not line.startswith("---")]
		)
		changes_info = Text("\nChanges: ", style="blue")
		changes_info.append(f"{added} added, {removed} removed")

		# Determine title for the panel
		panel_title = f"[bold]Group {index + 1} of {total}[/bold]"

		# Create diff panel
		diff_panel = Panel(
			Group(file_info, changes_info, diff_content),
			title=panel_title,
			border_style="cyan",
			expand=True,
			width=self.console.width,
			padding=(1, 2),
		)
		self.console.print(diff_panel)

		# Print divider
		self.console.print(Rule(style="dim"))

		# Create message panel if message exists
		if hasattr(group, "message") and group.message:
			# Create message panel
			message_panel = Panel(
				Text(str(group.message), style="green"),
				title="[bold blue]Generated message[/]",
				border_style="green",
				expand=True,
				width=self.console.width,
				padding=(1, 2),
			)
			self.console.print(message_panel)
		else:
			self.console.print(
				Panel(
					Text("No message generated yet", style="dim"),
					title="[bold]Message[/]",
					border_style="yellow",
					expand=True,
					width=self.console.width,
					padding=(1, 2),
				)
			)

	def display_message(self, message: str, is_llm_generated: bool = False) -> None:
		"""
		Display a commit message to the user.

		Args:
		    message: The commit message to display
		    is_llm_generated: Whether the message was generated by an LLM

		"""
		tag = "AI" if is_llm_generated else "Simple"
		message_panel = Panel(
			Text(message, style="green"),
			title=f"[bold {'blue' if is_llm_generated else 'yellow'}]Proposed message ({tag})[/]",
			border_style="blue" if is_llm_generated else "yellow",
			expand=False,
			padding=(1, 2),
		)
		self.console.print(message_panel)

	def get_user_action(self) -> ChunkAction:
		"""
		Get the user's desired action for the current chunk.

		Returns:
		    ChunkAction indicating what to do with the chunk

		"""
		# Define options with their display text and corresponding action
		options: list[tuple[str, ChunkAction]] = [
			("Commit with this message", ChunkAction.COMMIT),
			("Edit message and commit", ChunkAction.EDIT),
			("Regenerate message", ChunkAction.REGENERATE),
			("Skip this chunk", ChunkAction.SKIP),
			("Exit without committing", ChunkAction.EXIT),
		]

		# Use questionary to get the user's choice
		result = questionary.select(
			"What would you like to do?",
			choices=[option[0] for option in options],
			default=options[0][0],  # Set "Commit with this message" as default
			qmark="»",
			use_indicator=True,
			use_arrow_keys=True,
		).ask()

		# Map the result back to the ChunkAction
		for option, action in options:
			if option == result:
				return action

		# Fallback (should never happen)
		return ChunkAction.EXIT

	def get_user_action_on_lint_failure(self) -> ChunkAction:
		"""
		Get the user's desired action when linting fails.

		Returns:
		    ChunkAction indicating what to do.

		"""
		options: list[tuple[str, ChunkAction]] = [
			("Regenerate message", ChunkAction.REGENERATE),
			("Bypass linter and commit with --no-verify", ChunkAction.COMMIT),
			("Edit message manually", ChunkAction.EDIT),
			("Skip this chunk", ChunkAction.SKIP),
			("Exit without committing", ChunkAction.EXIT),
		]
		result = questionary.select(
			"Linting failed. What would you like to do?",
			choices=[option[0] for option in options],
			qmark="?»",  # Use a different qmark to indicate failure state
			use_indicator=True,
			use_arrow_keys=True,
		).ask()
		for option, action in options:
			if option == result:
				return action
		return ChunkAction.EXIT  # Fallback

	def edit_message(self, current_message: str) -> str:
		"""
		Get an edited commit message from the user.

		Args:
		    current_message: Current commit message

		Returns:
		    Edited commit message

		"""
		self.console.print("\n[bold blue]Edit commit message:[/]")
		self.console.print("[dim]Press Enter to keep current message[/]")
		return Prompt.ask("Message", default=current_message)

	def process_chunk(self, chunk: DiffChunk, index: int = 0, total: int = 1) -> ChunkResult:
		"""
		Process a single diff chunk interactively.

		Args:
		    chunk: DiffChunk to process
		    index: The 0-based index of the current chunk
		    total: The total number of chunks

		Returns:
		    ChunkResult with the user's action and any modified message

		"""
		# Display the combined diff and message panel
		self.display_chunk(chunk, index, total)

		# Now get the user's action through questionary (without displaying another message panel)
		action = self.get_user_action()

		if action == ChunkAction.EDIT:
			message = self.edit_message(chunk.description or "")
			return ChunkResult(ChunkAction.COMMIT, message)

		if action == ChunkAction.COMMIT:
			return ChunkResult(action, chunk.description)

		return ChunkResult(action)

	def confirm_abort(self) -> bool:
		"""
		Ask the user to confirm aborting the commit process.

		Returns:
		    True if the user confirms, False otherwise

		Raises:
		    typer.Exit: When the user confirms exiting

		"""
		confirmed = Confirm.ask(
			"\n[bold yellow]Are you sure you want to exit without committing?[/]",
			default=False,
		)

		if confirmed:
			self.console.print("[yellow]Exiting commit process...[/yellow]")
			# Use a zero exit code to indicate a successful (intended) exit
			# This prevents error messages from showing when exiting
			raise typer.Exit(code=0)

		return False

	def confirm_bypass_hooks(self) -> ChunkAction:
		"""
		Ask the user what to do when git hooks fail.

		Returns:
		    ChunkAction indicating what to do next

		"""
		self.console.print("\n[bold yellow]Git hooks failed.[/]")
		self.console.print("[yellow]This may be due to linting or other pre-commit checks.[/]")

		options: list[tuple[str, ChunkAction]] = [
			("Force commit and bypass hooks", ChunkAction.COMMIT),
			("Regenerate message and try again", ChunkAction.REGENERATE),
			("Edit message manually", ChunkAction.EDIT),
			("Skip this group", ChunkAction.SKIP),
			("Exit without committing", ChunkAction.EXIT),
		]

		result = questionary.select(
			"What would you like to do?",
			choices=[option[0] for option in options],
			qmark="»",
			use_indicator=True,
			use_arrow_keys=True,
		).ask()

		for option, action in options:
			if option == result:
				return action

		# Fallback (should never happen)
		return ChunkAction.EXIT

	def show_success(self, message: str) -> None:
		"""
		Show a success message.

		Args:
		    message: Message to display

		"""
		self.console.print(f"\n[bold green]✓[/] {message}")

	def show_warning(self, message: str) -> None:
		"""
		Show a warning message to the user.

		Args:
		    message: Warning message to display

		"""
		self.console.print(f"\n[bold yellow]⚠[/] {message}")

	def show_error(self, message: str) -> None:
		"""
		Show an error message to the user.

		Args:
		    message: Error message to display

		"""
		if "No changes to commit" in message:
			# This is an informational message, not an error
			self.console.print(f"[yellow]{message}[/yellow]")
		else:
			# This is a real error
			self.console.print(f"[red]Error:[/red] {message}")

	def show_skipped(self, files: list[str]) -> None:
		"""
		Show which files were skipped.

		Args:
		    files: List of skipped files

		"""
		if files:
			self.console.print("\n[yellow]Skipped changes in:[/]")
			for file in files:
				self.console.print(f"  • {file}")

	def show_message(self, message: str) -> None:
		"""
		Show a general informational message.

		Args:
		    message: Message to display

		"""
		self.console.print(f"\n{message}")

	def show_regenerating(self) -> None:
		"""Show message indicating message regeneration."""
		self.console.print("\n[yellow]Regenerating commit message...[/yellow]")

	def show_all_committed(self) -> None:
		"""Show message indicating all changes are committed."""
		self.console.print("[green]✓[/green] All changes committed!")

	def show_all_done(self) -> None:
		"""
		Show a final success message when the process completes.

		This is an alias for show_all_committed for now, but could be
		customized.

		"""
		self.show_all_committed()

	def show_lint_errors(self, errors: list[str]) -> None:
		"""Display linting errors to the user."""
		self.console.print("[bold red]Commit message failed linting:[/bold red]")
		for error in errors:
			self.console.print(f"  - {error}")

	def confirm_commit_with_lint_errors(self) -> bool:
		"""Ask the user if they want to commit despite lint errors."""
		return questionary.confirm("Commit message has lint errors. Commit anyway?", default=False).ask()

	def confirm_exit(self) -> bool:
		"""Ask the user to confirm exiting without committing."""
		return questionary.confirm("Are you sure you want to exit without committing?", default=False).ask()

	def display_failed_lint_message(self, message: str, lint_errors: list[str], is_llm_generated: bool = False) -> None:
		"""
		Display a commit message that failed linting, along with the errors.

		Args:
		    message: The commit message to display.
		    lint_errors: List of linting error messages.
		    is_llm_generated: Whether the message was generated by an LLM.

		"""
		tag = "AI" if is_llm_generated else "Simple"
		message_panel = Panel(
			Text(message, style="yellow"),  # Use yellow style for the message text
			title=f"[bold yellow]Proposed message ({tag}) - LINTING FAILED[/]",
			border_style="yellow",  # Yellow border to indicate warning/failure
			expand=False,
			padding=(1, 2),
		)
		self.console.print(message_panel)

		# Display lint errors below
		if lint_errors:
			error_text = Text("\n".join([f"- {err}" for err in lint_errors]), style="red")
			error_panel = Panel(
				error_text,
				title="[bold red]Linting Errors[/]",
				border_style="red",
				expand=False,
				padding=(1, 2),
			)
			self.console.print(error_panel)

	def get_group_action(self) -> ChunkAction:
		"""
		Get the user's desired action for the current semantic group.

		Returns:
		        ChunkAction indicating what to do with the group

		"""
		# Define options with their display text and corresponding action
		options: list[tuple[str, ChunkAction]] = [
			("Commit this group", ChunkAction.COMMIT),
			("Edit message and commit", ChunkAction.EDIT),
			("Regenerate message", ChunkAction.REGENERATE),
			("Skip this group", ChunkAction.SKIP),
			("Exit without committing", ChunkAction.EXIT),
		]

		# Use questionary to get the user's choice
		result = questionary.select(
			"What would you like to do with this group?",
			choices=[option[0] for option in options],
			default=options[0][0],  # Set "Commit this group" as default
			qmark="»",
			use_indicator=True,
			use_arrow_keys=True,
		).ask()

		# Map the result back to the ChunkAction
		for option, action in options:
			if option == result:
				return action

		# Fallback (should never happen)
		return ChunkAction.EXIT

__init__

__init__() -> None

Initialize the commit UI.

Source code in src/codemap/git/interactive.py

def __init__(self) -> None:
	"""Initialize the commit UI."""
	self.console = Console()

console instance-attribute

console = Console()

display_chunk

display_chunk(
	chunk: DiffChunk, index: int = 0, total: int = 1
) -> None

Display a diff chunk to the user.

Parameters:

Name	Type	Description	Default
chunk	DiffChunk	DiffChunk to display	required
index	int	The 0-based index of the current chunk	0
total	int	The total number of chunks	1

Source code in src/codemap/git/interactive.py

def display_chunk(self, chunk: DiffChunk, index: int = 0, total: int = 1) -> None:
	"""
	Display a diff chunk to the user.

	Args:
	    chunk: DiffChunk to display
	    index: The 0-based index of the current chunk
	    total: The total number of chunks

	"""
	# Build file information
	file_info = Text("Files: ", style="blue")
	file_info.append(", ".join(chunk.files))

	# Calculate changes
	added = len(
		[line for line in chunk.content.splitlines() if line.startswith("+") and not line.startswith("+++")]
	)
	removed = len(
		[line for line in chunk.content.splitlines() if line.startswith("-") and not line.startswith("---")]
	)
	changes_info = Text("\nChanges: ", style="blue")
	changes_info.append(f"{added} added, {removed} removed")

	# Prepare diff content
	panel_content = chunk.content
	if not panel_content.strip():
		panel_content = "No content diff available (e.g., new file or mode change)"

	# Truncate to maximum of MAX_PREVIEW_LINES lines
	content_lines = panel_content.splitlines()
	if len(content_lines) > MAX_PREVIEW_LINES:
		remaining_lines = len(content_lines) - MAX_PREVIEW_LINES
		panel_content = "\n".join(content_lines[:MAX_PREVIEW_LINES]) + f"\n... ({remaining_lines} more lines)"

	diff_content = Text("\n" + panel_content)

	# Determine title for the panel - use provided index and total
	panel_title = f"[bold]Commit {index + 1} of {total}[/bold]"

	# Create content for the panel conditionally
	if getattr(chunk, "description", None):
		# If there's a description, create a combined panel
		if getattr(chunk, "is_llm_generated", False):
			message_title = "[bold blue]Proposed message (AI)[/]"
			message_style = "blue"
		else:
			message_title = "[bold yellow]Proposed message (Simple)[/]"
			message_style = "yellow"

		# Create separate panels and print them
		# First, print the diff panel
		diff_panel = Panel(
			Group(file_info, changes_info, diff_content),
			title=panel_title,
			border_style="cyan",
			expand=True,
			width=self.console.width,
			padding=(1, 2),
		)
		self.console.print(diff_panel)

		# Print divider
		self.console.print(Rule(style="dim"))

		# Then print the message panel
		message_panel = Panel(
			Text(str(chunk.description), style="green"),
			title=message_title,
			border_style=message_style,
			expand=True,
			width=self.console.width,
			padding=(1, 2),
		)
		self.console.print(message_panel)
	else:
		# If no description, just print the diff panel
		panel = Panel(
			Group(file_info, changes_info, diff_content),
			title=panel_title,
			border_style="cyan",
			expand=True,
			width=self.console.width,
			padding=(1, 2),
		)
		self.console.print()
		self.console.print(panel)
		self.console.print()

display_group

display_group(
	group: SemanticGroup, index: int = 0, total: int = 1
) -> None

Display a semantic group to the user.

Parameters:

Name	Type	Description	Default
group	SemanticGroup	SemanticGroup to display	required
index	int	The 0-based index of the current group	0
total	int	The total number of groups	1

Source code in src/codemap/git/interactive.py

def display_group(self, group: SemanticGroup, index: int = 0, total: int = 1) -> None:
	"""
	Display a semantic group to the user.

	Args:
	        group: SemanticGroup to display
	        index: The 0-based index of the current group
	        total: The total number of groups

	"""
	# Build file information
	file_list = "\n".join([f"  - {file}" for file in group.files])
	file_info = Text(f"Files ({len(group.files)}):\n", style="blue")
	file_info.append(file_list)

	# Prepare diff preview - show first few lines of diff content
	diff_preview = group.content
	content_lines = diff_preview.splitlines()
	if len(content_lines) > MAX_PREVIEW_LINES:
		remaining_lines = len(content_lines) - MAX_PREVIEW_LINES
		diff_preview = "\n".join(content_lines[:MAX_PREVIEW_LINES]) + f"\n... ({remaining_lines} more lines)"
	diff_content = Text("\n\nDiff Preview:\n", style="blue")
	diff_content.append(diff_preview)

	# Calculate changes
	added = len(
		[line for line in group.content.splitlines() if line.startswith("+") and not line.startswith("+++")]
	)
	removed = len(
		[line for line in group.content.splitlines() if line.startswith("-") and not line.startswith("---")]
	)
	changes_info = Text("\nChanges: ", style="blue")
	changes_info.append(f"{added} added, {removed} removed")

	# Determine title for the panel
	panel_title = f"[bold]Group {index + 1} of {total}[/bold]"

	# Create diff panel
	diff_panel = Panel(
		Group(file_info, changes_info, diff_content),
		title=panel_title,
		border_style="cyan",
		expand=True,
		width=self.console.width,
		padding=(1, 2),
	)
	self.console.print(diff_panel)

	# Print divider
	self.console.print(Rule(style="dim"))

	# Create message panel if message exists
	if hasattr(group, "message") and group.message:
		# Create message panel
		message_panel = Panel(
			Text(str(group.message), style="green"),
			title="[bold blue]Generated message[/]",
			border_style="green",
			expand=True,
			width=self.console.width,
			padding=(1, 2),
		)
		self.console.print(message_panel)
	else:
		self.console.print(
			Panel(
				Text("No message generated yet", style="dim"),
				title="[bold]Message[/]",
				border_style="yellow",
				expand=True,
				width=self.console.width,
				padding=(1, 2),
			)
		)

display_message

display_message(
	message: str, is_llm_generated: bool = False
) -> None

Display a commit message to the user.

Parameters:

Name	Type	Description	Default
message	str	The commit message to display	required
is_llm_generated	bool	Whether the message was generated by an LLM	False

Source code in src/codemap/git/interactive.py

def display_message(self, message: str, is_llm_generated: bool = False) -> None:
	"""
	Display a commit message to the user.

	Args:
	    message: The commit message to display
	    is_llm_generated: Whether the message was generated by an LLM

	"""
	tag = "AI" if is_llm_generated else "Simple"
	message_panel = Panel(
		Text(message, style="green"),
		title=f"[bold {'blue' if is_llm_generated else 'yellow'}]Proposed message ({tag})[/]",
		border_style="blue" if is_llm_generated else "yellow",
		expand=False,
		padding=(1, 2),
	)
	self.console.print(message_panel)

get_user_action

get_user_action() -> ChunkAction

Get the user's desired action for the current chunk.

Returns:

Type	Description
ChunkAction	ChunkAction indicating what to do with the chunk

Source code in src/codemap/git/interactive.py

def get_user_action(self) -> ChunkAction:
	"""
	Get the user's desired action for the current chunk.

	Returns:
	    ChunkAction indicating what to do with the chunk

	"""
	# Define options with their display text and corresponding action
	options: list[tuple[str, ChunkAction]] = [
		("Commit with this message", ChunkAction.COMMIT),
		("Edit message and commit", ChunkAction.EDIT),
		("Regenerate message", ChunkAction.REGENERATE),
		("Skip this chunk", ChunkAction.SKIP),
		("Exit without committing", ChunkAction.EXIT),
	]

	# Use questionary to get the user's choice
	result = questionary.select(
		"What would you like to do?",
		choices=[option[0] for option in options],
		default=options[0][0],  # Set "Commit with this message" as default
		qmark="»",
		use_indicator=True,
		use_arrow_keys=True,
	).ask()

	# Map the result back to the ChunkAction
	for option, action in options:
		if option == result:
			return action

	# Fallback (should never happen)
	return ChunkAction.EXIT

get_user_action_on_lint_failure

get_user_action_on_lint_failure() -> ChunkAction

Get the user's desired action when linting fails.

Returns:

Type	Description
ChunkAction	ChunkAction indicating what to do.

Source code in src/codemap/git/interactive.py

def get_user_action_on_lint_failure(self) -> ChunkAction:
	"""
	Get the user's desired action when linting fails.

	Returns:
	    ChunkAction indicating what to do.

	"""
	options: list[tuple[str, ChunkAction]] = [
		("Regenerate message", ChunkAction.REGENERATE),
		("Bypass linter and commit with --no-verify", ChunkAction.COMMIT),
		("Edit message manually", ChunkAction.EDIT),
		("Skip this chunk", ChunkAction.SKIP),
		("Exit without committing", ChunkAction.EXIT),
	]
	result = questionary.select(
		"Linting failed. What would you like to do?",
		choices=[option[0] for option in options],
		qmark="?»",  # Use a different qmark to indicate failure state
		use_indicator=True,
		use_arrow_keys=True,
	).ask()
	for option, action in options:
		if option == result:
			return action
	return ChunkAction.EXIT  # Fallback

edit_message

edit_message(current_message: str) -> str

Get an edited commit message from the user.

Parameters:

Name	Type	Description	Default
current_message	str	Current commit message	required

Returns:

Type	Description
str	Edited commit message

Source code in src/codemap/git/interactive.py

def edit_message(self, current_message: str) -> str:
	"""
	Get an edited commit message from the user.

	Args:
	    current_message: Current commit message

	Returns:
	    Edited commit message

	"""
	self.console.print("\n[bold blue]Edit commit message:[/]")
	self.console.print("[dim]Press Enter to keep current message[/]")
	return Prompt.ask("Message", default=current_message)

process_chunk

process_chunk(
	chunk: DiffChunk, index: int = 0, total: int = 1
) -> ChunkResult

Process a single diff chunk interactively.

Parameters:

Name	Type	Description	Default
chunk	DiffChunk	DiffChunk to process	required
index	int	The 0-based index of the current chunk	0
total	int	The total number of chunks	1

Returns:

Type	Description
ChunkResult	ChunkResult with the user's action and any modified message

Source code in src/codemap/git/interactive.py

def process_chunk(self, chunk: DiffChunk, index: int = 0, total: int = 1) -> ChunkResult:
	"""
	Process a single diff chunk interactively.

	Args:
	    chunk: DiffChunk to process
	    index: The 0-based index of the current chunk
	    total: The total number of chunks

	Returns:
	    ChunkResult with the user's action and any modified message

	"""
	# Display the combined diff and message panel
	self.display_chunk(chunk, index, total)

	# Now get the user's action through questionary (without displaying another message panel)
	action = self.get_user_action()

	if action == ChunkAction.EDIT:
		message = self.edit_message(chunk.description or "")
		return ChunkResult(ChunkAction.COMMIT, message)

	if action == ChunkAction.COMMIT:
		return ChunkResult(action, chunk.description)

	return ChunkResult(action)

confirm_abort

confirm_abort() -> bool

Ask the user to confirm aborting the commit process.

Returns:

Type	Description
bool	True if the user confirms, False otherwise

Raises:

Type	Description
Exit	When the user confirms exiting

Source code in src/codemap/git/interactive.py

def confirm_abort(self) -> bool:
	"""
	Ask the user to confirm aborting the commit process.

	Returns:
	    True if the user confirms, False otherwise

	Raises:
	    typer.Exit: When the user confirms exiting

	"""
	confirmed = Confirm.ask(
		"\n[bold yellow]Are you sure you want to exit without committing?[/]",
		default=False,
	)

	if confirmed:
		self.console.print("[yellow]Exiting commit process...[/yellow]")
		# Use a zero exit code to indicate a successful (intended) exit
		# This prevents error messages from showing when exiting
		raise typer.Exit(code=0)

	return False

confirm_bypass_hooks

confirm_bypass_hooks() -> ChunkAction

Ask the user what to do when git hooks fail.

Returns:

Type	Description
ChunkAction	ChunkAction indicating what to do next

Source code in src/codemap/git/interactive.py

def confirm_bypass_hooks(self) -> ChunkAction:
	"""
	Ask the user what to do when git hooks fail.

	Returns:
	    ChunkAction indicating what to do next

	"""
	self.console.print("\n[bold yellow]Git hooks failed.[/]")
	self.console.print("[yellow]This may be due to linting or other pre-commit checks.[/]")

	options: list[tuple[str, ChunkAction]] = [
		("Force commit and bypass hooks", ChunkAction.COMMIT),
		("Regenerate message and try again", ChunkAction.REGENERATE),
		("Edit message manually", ChunkAction.EDIT),
		("Skip this group", ChunkAction.SKIP),
		("Exit without committing", ChunkAction.EXIT),
	]

	result = questionary.select(
		"What would you like to do?",
		choices=[option[0] for option in options],
		qmark="»",
		use_indicator=True,
		use_arrow_keys=True,
	).ask()

	for option, action in options:
		if option == result:
			return action

	# Fallback (should never happen)
	return ChunkAction.EXIT

show_success

show_success(message: str) -> None

Show a success message.

Parameters:

Name	Type	Description	Default
message	str	Message to display	required

Source code in src/codemap/git/interactive.py

def show_success(self, message: str) -> None:
	"""
	Show a success message.

	Args:
	    message: Message to display

	"""
	self.console.print(f"\n[bold green]✓[/] {message}")

show_warning

show_warning(message: str) -> None

Show a warning message to the user.

Parameters:

Name	Type	Description	Default
message	str	Warning message to display	required

Source code in src/codemap/git/interactive.py

def show_warning(self, message: str) -> None:
	"""
	Show a warning message to the user.

	Args:
	    message: Warning message to display

	"""
	self.console.print(f"\n[bold yellow]⚠[/] {message}")

show_error

show_error(message: str) -> None

Show an error message to the user.

Parameters:

Name	Type	Description	Default
message	str	Error message to display	required

Source code in src/codemap/git/interactive.py

def show_error(self, message: str) -> None:
	"""
	Show an error message to the user.

	Args:
	    message: Error message to display

	"""
	if "No changes to commit" in message:
		# This is an informational message, not an error
		self.console.print(f"[yellow]{message}[/yellow]")
	else:
		# This is a real error
		self.console.print(f"[red]Error:[/red] {message}")

show_skipped

show_skipped(files: list[str]) -> None

Show which files were skipped.

Parameters:

Name	Type	Description	Default
files	list[str]	List of skipped files	required

Source code in src/codemap/git/interactive.py

def show_skipped(self, files: list[str]) -> None:
	"""
	Show which files were skipped.

	Args:
	    files: List of skipped files

	"""
	if files:
		self.console.print("\n[yellow]Skipped changes in:[/]")
		for file in files:
			self.console.print(f"  • {file}")

show_message

show_message(message: str) -> None

Show a general informational message.

Parameters:

Name	Type	Description	Default
message	str	Message to display	required

Source code in src/codemap/git/interactive.py

def show_message(self, message: str) -> None:
	"""
	Show a general informational message.

	Args:
	    message: Message to display

	"""
	self.console.print(f"\n{message}")

show_regenerating

show_regenerating() -> None

Show message indicating message regeneration.

Source code in src/codemap/git/interactive.py

def show_regenerating(self) -> None:
	"""Show message indicating message regeneration."""
	self.console.print("\n[yellow]Regenerating commit message...[/yellow]")

show_all_committed

show_all_committed() -> None

Show message indicating all changes are committed.

Source code in src/codemap/git/interactive.py

def show_all_committed(self) -> None:
	"""Show message indicating all changes are committed."""
	self.console.print("[green]✓[/green] All changes committed!")

show_all_done

show_all_done() -> None

Show a final success message when the process completes.

This is an alias for show_all_committed for now, but could be customized.

Source code in src/codemap/git/interactive.py

def show_all_done(self) -> None:
	"""
	Show a final success message when the process completes.

	This is an alias for show_all_committed for now, but could be
	customized.

	"""
	self.show_all_committed()

show_lint_errors

show_lint_errors(errors: list[str]) -> None

Display linting errors to the user.

Source code in src/codemap/git/interactive.py

def show_lint_errors(self, errors: list[str]) -> None:
	"""Display linting errors to the user."""
	self.console.print("[bold red]Commit message failed linting:[/bold red]")
	for error in errors:
		self.console.print(f"  - {error}")

confirm_commit_with_lint_errors

confirm_commit_with_lint_errors() -> bool

Ask the user if they want to commit despite lint errors.

Source code in src/codemap/git/interactive.py

def confirm_commit_with_lint_errors(self) -> bool:
	"""Ask the user if they want to commit despite lint errors."""
	return questionary.confirm("Commit message has lint errors. Commit anyway?", default=False).ask()

confirm_exit

confirm_exit() -> bool

Ask the user to confirm exiting without committing.

Source code in src/codemap/git/interactive.py

def confirm_exit(self) -> bool:
	"""Ask the user to confirm exiting without committing."""
	return questionary.confirm("Are you sure you want to exit without committing?", default=False).ask()

display_failed_lint_message

display_failed_lint_message(
	message: str,
	lint_errors: list[str],
	is_llm_generated: bool = False,
) -> None

Display a commit message that failed linting, along with the errors.

Parameters:

Name	Type	Description	Default
message	str	The commit message to display.	required
lint_errors	list[str]	List of linting error messages.	required
is_llm_generated	bool	Whether the message was generated by an LLM.	False

Source code in src/codemap/git/interactive.py

def display_failed_lint_message(self, message: str, lint_errors: list[str], is_llm_generated: bool = False) -> None:
	"""
	Display a commit message that failed linting, along with the errors.

	Args:
	    message: The commit message to display.
	    lint_errors: List of linting error messages.
	    is_llm_generated: Whether the message was generated by an LLM.

	"""
	tag = "AI" if is_llm_generated else "Simple"
	message_panel = Panel(
		Text(message, style="yellow"),  # Use yellow style for the message text
		title=f"[bold yellow]Proposed message ({tag}) - LINTING FAILED[/]",
		border_style="yellow",  # Yellow border to indicate warning/failure
		expand=False,
		padding=(1, 2),
	)
	self.console.print(message_panel)

	# Display lint errors below
	if lint_errors:
		error_text = Text("\n".join([f"- {err}" for err in lint_errors]), style="red")
		error_panel = Panel(
			error_text,
			title="[bold red]Linting Errors[/]",
			border_style="red",
			expand=False,
			padding=(1, 2),
		)
		self.console.print(error_panel)

get_group_action

get_group_action() -> ChunkAction

Get the user's desired action for the current semantic group.

Returns:

Type	Description
ChunkAction	ChunkAction indicating what to do with the group

Source code in src/codemap/git/interactive.py

def get_group_action(self) -> ChunkAction:
	"""
	Get the user's desired action for the current semantic group.

	Returns:
	        ChunkAction indicating what to do with the group

	"""
	# Define options with their display text and corresponding action
	options: list[tuple[str, ChunkAction]] = [
		("Commit this group", ChunkAction.COMMIT),
		("Edit message and commit", ChunkAction.EDIT),
		("Regenerate message", ChunkAction.REGENERATE),
		("Skip this group", ChunkAction.SKIP),
		("Exit without committing", ChunkAction.EXIT),
	]

	# Use questionary to get the user's choice
	result = questionary.select(
		"What would you like to do with this group?",
		choices=[option[0] for option in options],
		default=options[0][0],  # Set "Commit this group" as default
		qmark="»",
		use_indicator=True,
		use_arrow_keys=True,
	).ask()

	# Map the result back to the ChunkAction
	for option, action in options:
		if option == result:
			return action

	# Fallback (should never happen)
	return ChunkAction.EXIT

utils

Git utilities for CodeMap.

logger module-attribute

logger = getLogger(__name__)

GitDiff dataclass

Represents a Git diff chunk.

Source code in src/codemap/git/utils.py

@dataclass
class GitDiff:
	"""Represents a Git diff chunk."""

	files: list[str]
	content: str
	is_staged: bool = False
	is_untracked: bool = False

__init__

__init__(
	files: list[str],
	content: str,
	is_staged: bool = False,
	is_untracked: bool = False,
) -> None

files instance-attribute

files: list[str]

content instance-attribute

content: str

is_staged class-attribute instance-attribute

is_staged: bool = False

is_untracked class-attribute instance-attribute

is_untracked: bool = False

GitError

Bases: Exception

Custom exception for Git-related errors.

Source code in src/codemap/git/utils.py

class GitError(Exception):
	"""Custom exception for Git-related errors."""

run_git_command

run_git_command(
	command: list[str],
	cwd: Path | str | None = None,
	environment: dict[str, str] | None = None,
) -> str

Run a git command and return its output.

Parameters:

Name	Type	Description	Default
command	list[str]	Command to run as a list of string arguments	required
cwd	Path | str | None	Working directory to run the command in	None
environment	dict[str, str] | None	Environment variables to use	None

Returns:

Type	Description
str	The output from the command

Raises:

Type	Description
GitError	If the git command fails

Source code in src/codemap/git/utils.py

def run_git_command(
	command: list[str],
	cwd: Path | str | None = None,
	environment: dict[str, str] | None = None,
) -> str:
	"""
	Run a git command and return its output.

	Args:
	    command: Command to run as a list of string arguments
	    cwd: Working directory to run the command in
	    environment: Environment variables to use

	Returns:
	    The output from the command

	Raises:
	    GitError: If the git command fails

	"""
	try:
		# Using subprocess.run with a list of arguments is safe since we're not using shell=True
		# and the command is not being built from untrusted input
		result = subprocess.run(  # noqa: S603
			command,
			cwd=cwd,
			capture_output=True,
			text=True,
			check=True,
			env=environment,
		)
		return result.stdout.strip()
	except subprocess.CalledProcessError as e:
		# Check if this is a pre-commit hook failure for commit - handled specially by the UI
		if command and len(command) > 1 and command[1] == "commit":
			if "pre-commit" in (e.stderr or ""):
				# This is a pre-commit hook failure - which is handled by the UI, so don't log as exception
				logger.warning("Git hooks failed: %s", e.stderr)
				msg = f"{e.stderr}"
				raise GitError(msg) from e
			# Regular commit error
			logger.exception("Git command failed: %s", " ".join(command))

		cmd_str = " ".join(command)
		error_output = e.stderr or ""
		error_msg = f"Git command failed: {cmd_str}\n{error_output}"
		logger.exception(error_msg)
		raise GitError(error_output or error_msg) from e
	except Exception as e:
		error_msg = f"Error running git command: {e}"
		logger.exception(error_msg)
		raise GitError(error_msg) from e

get_repo_root

get_repo_root(path: Path | None = None) -> Path

Get the root directory of the Git repository.

Parameters:

Name	Type	Description	Default
path	Path | None	Optional path to start searching from	None

Returns:

Type	Description
Path	Path to repository root

Raises:

Type	Description
GitError	If not in a Git repository

Source code in src/codemap/git/utils.py

def get_repo_root(path: Path | None = None) -> Path:
	"""
	Get the root directory of the Git repository.

	Args:
	    path: Optional path to start searching from

	Returns:
	    Path to repository root

	Raises:
	    GitError: If not in a Git repository

	"""
	try:
		result = run_git_command(["git", "rev-parse", "--show-toplevel"], path)
		return Path(result.strip())
	except GitError as e:
		msg = "Not in a Git repository"
		raise GitError(msg) from e

validate_repo_path

validate_repo_path(path: Path | None = None) -> Path | None

Validate and return the repository path.

Parameters:

Name	Type	Description	Default
path	Path | None	Optional path to validate (defaults to current directory)	None

Returns:

Type	Description
Path | None	Path to the repository root if valid, None otherwise

Source code in src/codemap/git/utils.py

def validate_repo_path(path: Path | None = None) -> Path | None:
	"""
	Validate and return the repository path.

	Args:
	    path: Optional path to validate (defaults to current directory)

	Returns:
	    Path to the repository root if valid, None otherwise

	"""
	try:
		# If no path provided, use current directory
		if path is None:
			path = Path.cwd()

		# Get the repository root
		return get_repo_root(path)
	except GitError:
		return None

get_staged_diff

get_staged_diff() -> GitDiff

Get the diff of staged changes.

Returns:

Type	Description
GitDiff	GitDiff object containing staged changes

Raises:

Type	Description
GitError	If git command fails

Source code in src/codemap/git/utils.py

def get_staged_diff() -> GitDiff:
	"""
	Get the diff of staged changes.

	Returns:
	    GitDiff object containing staged changes

	Raises:
	    GitError: If git command fails

	"""
	try:
		# Get list of staged files
		staged_files = run_git_command(["git", "diff", "--cached", "--name-only"]).splitlines()

		# Get the actual diff
		diff_content = run_git_command(["git", "diff", "--cached"])

		return GitDiff(
			files=staged_files,
			content=diff_content,
			is_staged=True,
		)
	except GitError as e:
		msg = "Failed to get staged changes"
		raise GitError(msg) from e

get_unstaged_diff

get_unstaged_diff() -> GitDiff

Get the diff of unstaged changes.

Returns:

Type	Description
GitDiff	GitDiff object containing unstaged changes

Raises:

Type	Description
GitError	If git command fails

Source code in src/codemap/git/utils.py

def get_unstaged_diff() -> GitDiff:
	"""
	Get the diff of unstaged changes.

	Returns:
	    GitDiff object containing unstaged changes

	Raises:
	    GitError: If git command fails

	"""
	try:
		# Get list of modified files
		modified_files = run_git_command(["git", "diff", "--name-only"]).splitlines()

		# Get the actual diff
		diff_content = run_git_command(["git", "diff"])

		return GitDiff(
			files=modified_files,
			content=diff_content,
			is_staged=False,
		)
	except GitError as e:
		msg = "Failed to get unstaged changes"
		raise GitError(msg) from e

stage_files

stage_files(files: list[str]) -> None

Stage the specified files.

This function intelligently handles both existing and deleted files: - For existing files, it uses git add - For files that no longer exist but are tracked by git, it uses git rm - For files that no longer exist but are still in index, it uses git rm --cached

This prevents errors when trying to stage files that have been deleted but not yet tracked in git.

Parameters:

Name	Type	Description	Default
files	list[str]	List of files to stage	required

Raises:

Type	Description
GitError	If staging fails

Source code in src/codemap/git/utils.py

def stage_files(files: list[str]) -> None:
	"""
	Stage the specified files.

	This function intelligently handles both existing and deleted files:
	- For existing files, it uses `git add`
	- For files that no longer exist but are tracked by git, it uses `git rm`
	- For files that no longer exist but are still in index, it uses `git rm --cached`

	This prevents errors when trying to stage files that have been deleted
	but not yet tracked in git.

	Args:
	    files: List of files to stage

	Raises:
	    GitError: If staging fails

	"""
	if not files:
		logger.warning("No files provided to stage_files")
		return

	# Keep track of all errors to report at the end
	errors = []

	try:
		# 1. Get information about file status
		# ====================================
		git_status_info = {}
		tracked_files = set()
		index_files = set()

		# 1.1 Get git status information
		try:
			status_output = run_git_command(["git", "status", "--porcelain"])
			for line in status_output.splitlines():
				# Ensure line is a string, not bytes
				line_str = line if isinstance(line, str) else line.decode("utf-8")
				if not line_str:
					continue

				status = line_str[:2]
				file_path = line_str[3:].strip()
				git_status_info[file_path] = status
		except GitError:
			errors.append("Failed to get git status information")

		# 1.2 Get tracked files
		try:
			tracked_files_output = run_git_command(["git", "ls-files"])
			tracked_files = set(tracked_files_output.splitlines())
		except GitError:
			errors.append("Failed to get list of tracked files")

		# 1.3 Get index files
		try:
			index_files_output = run_git_command(["git", "ls-files", "--stage"])
			index_files = {line.split()[-1] for line in index_files_output.splitlines() if line.strip()}
		except GitError:
			errors.append("Failed to get list of files in git index")

		# 2. Filter and categorize files
		# ==============================
		# Filter out invalid filenames
		valid_files = [
			file
			for file in files
			if not (any(char in file for char in ["*", "+", "{", "}", "\\"]) or file.startswith('"'))
		]

		# Skip any invalid filenames that were filtered out
		for file in files:
			if file not in valid_files:
				logger.warning("Skipping invalid filename: %s", file)

		# Categorize files
		existing_files = []
		deleted_tracked_files = []
		deleted_index_files = []
		untracked_nonexistent_files = []

		for file in valid_files:
			path = Path(file)
			if path.exists():
				existing_files.append(file)
			elif file in tracked_files:
				deleted_tracked_files.append(file)
			elif file in index_files:
				deleted_index_files.append(file)
			else:
				untracked_nonexistent_files.append(file)
				logger.warning("Skipping file %s: Does not exist and is not tracked by git", file)

		# Log the categorized files
		logger.debug("Existing files (%d): %s", len(existing_files), existing_files)
		logger.debug("Deleted tracked files (%d): %s", len(deleted_tracked_files), deleted_tracked_files)
		logger.debug("Deleted index files (%d): %s", len(deleted_index_files), deleted_index_files)

		# 3. Process each file category
		# =============================
		# 3.1 Add existing files
		if existing_files:
			try:
				run_git_command(["git", "add", *existing_files])
				logger.debug("Added %d existing files", len(existing_files))
			except GitError as e:
				errors.append(f"Failed to add existing files: {e!s}")

		# 3.2 Remove deleted tracked files
		for file in deleted_tracked_files:
			cmd = ["git", "rm", file]
			try:
				run_git_command(cmd)
				logger.debug("Removed deleted tracked file: %s", file)
			except GitError as e:
				if "did not match any files" in str(e):
					# File exists in tracked_files but can't be found, try with --cached
					deleted_index_files.append(file)
				else:
					errors.append(f"Failed to remove deleted tracked file {file}: {e!s}")

		# 3.3 Remove files from index
		if deleted_index_files:
			try:
				run_git_command(["git", "rm", "--cached", *deleted_index_files])
				logger.debug("Removed %d files from index", len(deleted_index_files))
			except GitError as e:
				errors.append(f"Failed to remove files from index: {e!s}")

		# 4. Report errors if any occurred
		# ================================
		if errors:
			error_msg = "; ".join(errors)
			msg = f"Errors while staging files: {error_msg}"
			logger.error(msg)
			raise GitError(msg)

	except GitError:
		# Pass through GitError exceptions
		raise
	except Exception as e:
		# Wrap other exceptions in GitError
		msg = f"Unexpected error staging files: {e}"
		logger.exception(msg)
		raise GitError(msg) from e

commit

commit(message: str) -> None

Create a commit with the given message.

Parameters:

Name	Type	Description	Default
message	str	Commit message	required

Raises:

Type	Description
GitError	If commit fails

Source code in src/codemap/git/utils.py

def commit(message: str) -> None:
	"""
	Create a commit with the given message.

	Args:
	    message: Commit message

	Raises:
	    GitError: If commit fails

	"""
	try:
		# For commit messages, we need to ensure they're properly quoted
		# Use a shell command directly to ensure proper quoting
		import shlex

		quoted_message = shlex.quote(message)
		shell_command = f"git commit -m {quoted_message}"

		# Using shell=True is necessary for proper handling of quoted commit messages
		# Security is maintained by using shlex.quote to escape user input
		subprocess.run(  # noqa: S602
			shell_command,
			cwd=None,  # Use current dir
			capture_output=True,
			text=True,
			check=True,
			shell=True,  # Using shell=True for this operation
		)
	except subprocess.CalledProcessError as e:
		msg = f"Failed to create commit: {e.stderr}"
		raise GitError(msg) from e

get_other_staged_files

get_other_staged_files(
	targeted_files: list[str],
) -> list[str]

Get staged files that are not part of the targeted files.

Parameters:

Name	Type	Description	Default
targeted_files	list[str]	List of files that are meant to be committed	required

Returns:

Type	Description
list[str]	List of other staged files that might be committed inadvertently

Raises:

Type	Description
GitError	If git command fails

Source code in src/codemap/git/utils.py

def get_other_staged_files(targeted_files: list[str]) -> list[str]:
	"""
	Get staged files that are not part of the targeted files.

	Args:
	    targeted_files: List of files that are meant to be committed

	Returns:
	    List of other staged files that might be committed inadvertently

	Raises:
	    GitError: If git command fails

	"""
	try:
		# Get all staged files
		all_staged = run_git_command(["git", "diff", "--cached", "--name-only"]).splitlines()

		# Filter out the targeted files
		return [f for f in all_staged if f not in targeted_files]
	except GitError as e:
		msg = "Failed to check for other staged files"
		raise GitError(msg) from e

stash_staged_changes

stash_staged_changes(exclude_files: list[str]) -> bool

Temporarily stash staged changes except for specified files.

This is used to ensure only specific files are committed when other files might be mistakenly staged.

Parameters:

Name	Type	Description	Default
exclude_files	list[str]	Files to exclude from stashing (to keep staged)	required

Returns:

Type	Description
bool	Whether stashing was performed

Raises:

Type	Description
GitError	If git operations fail

Source code in src/codemap/git/utils.py

def stash_staged_changes(exclude_files: list[str]) -> bool:
	"""
	Temporarily stash staged changes except for specified files.

	This is used to ensure only specific files are committed when other
	files might be mistakenly staged.

	Args:
	    exclude_files: Files to exclude from stashing (to keep staged)

	Returns:
	    Whether stashing was performed

	Raises:
	    GitError: If git operations fail

	"""
	try:
		# First check if there are any other staged files
		other_files = get_other_staged_files(exclude_files)
		if not other_files:
			return False

		# Create a temporary index to save current state
		run_git_command(["git", "stash", "push", "--keep-index", "--message", "CodeMap: temporary stash for commit"])
	except GitError as e:
		msg = "Failed to stash other staged changes"
		raise GitError(msg) from e
	else:
		return True

unstash_changes

unstash_changes() -> None

Restore previously stashed changes.

Raises:

Type	Description
GitError	If git operations fail

Source code in src/codemap/git/utils.py

def unstash_changes() -> None:
	"""
	Restore previously stashed changes.

	Raises:
	    GitError: If git operations fail

	"""
	try:
		stash_list = run_git_command(["git", "stash", "list"])
		if "CodeMap: temporary stash for commit" in stash_list:
			run_git_command(["git", "stash", "pop"])
	except GitError as e:
		msg = "Failed to restore stashed changes; you may need to manually run 'git stash pop'"
		raise GitError(msg) from e

commit_only_files

commit_only_files(
	files: list[str],
	message: str,
	*,
	commit_options: list[str] | None = None,
	ignore_hooks: bool = False,
) -> list[str]

Commit only the specified files.

Parameters:

Name	Type	Description	Default
files	list[str]	List of files to commit	required
message	str	Commit message	required
commit_options	list[str] | None	Additional commit options	None
ignore_hooks	bool	Whether to ignore Git hooks	False

Returns:

Type	Description
list[str]	List of other staged files that weren't committed

Source code in src/codemap/git/utils.py

def commit_only_files(
	files: list[str], message: str, *, commit_options: list[str] | None = None, ignore_hooks: bool = False
) -> list[str]:
	"""
	Commit only the specified files.

	Args:
	    files: List of files to commit
	    message: Commit message
	    commit_options: Additional commit options
	    ignore_hooks: Whether to ignore Git hooks

	Returns:
	    List of other staged files that weren't committed

	"""
	try:
		# Get status to check for deleted files
		status_cmd = ["git", "status", "--porcelain"]
		result = subprocess.run(  # noqa: S603
			status_cmd,
			capture_output=True,
			text=True,
			check=True,
			shell=False,  # Explicitly set shell=False for security
		)
		status_output = result.stdout.strip()

		# Extract files from status output
		status_files = {}
		for line in status_output.splitlines():
			if not line.strip():
				continue
			status = line[:2].strip()
			file_path = line[3:].strip()

			# Handle renamed files
			if isinstance(file_path, bytes):
				file_path = file_path.decode("utf-8")

			if " -> " in file_path:
				file_path = file_path.split(" -> ")[1]

			status_files[file_path] = status

		# Stage all files - our improved stage_files function can handle both existing and deleted files
		stage_files(files)

		# Get other staged files
		other_staged = get_other_staged_files(files)

		# Commit the changes
		commit_cmd = ["git", "commit", "-m", message]

		if commit_options:
			commit_cmd.extend(commit_options)

		if ignore_hooks:
			commit_cmd.append("--no-verify")

		try:
			subprocess.run(  # noqa: S603
				commit_cmd,
				check=True,
				capture_output=True,
				text=True,
				shell=False,  # Explicitly set shell=False for security
			)
			logger.info("Created commit with message: %s", message)
		except subprocess.CalledProcessError as e:
			# Capture stderr and stdout for better error reporting
			error_msg = f"Git commit command failed. Command: '{' '.join(commit_cmd)}'"

			if e.stderr:
				error_msg += f"\n\nGit Error Output:\n{e.stderr.strip()}"
			if e.stdout:
				error_msg += f"\n\nCommand Output:\n{e.stdout.strip()}"

			logger.exception("Failed to create commit: %s", error_msg)
			raise GitError(error_msg) from e

		return other_staged
	except GitError:
		# Re-raise GitErrors directly
		raise
	except Exception as e:
		error_msg = f"Error in commit_only_files: {e!s}"
		logger.exception(error_msg)
		raise GitError(error_msg) from e

get_untracked_files

get_untracked_files() -> list[str]

Get a list of untracked files in the repository.

These are files that are not yet tracked by Git (new files that haven't been staged).

Returns:

Type	Description
list[str]	List of untracked file paths

Raises:

Type	Description
GitError	If git command fails

Source code in src/codemap/git/utils.py

def get_untracked_files() -> list[str]:
	"""
	Get a list of untracked files in the repository.

	These are files that are not yet tracked by Git (new files that haven't been staged).

	Returns:
	    List of untracked file paths

	Raises:
	    GitError: If git command fails

	"""
	try:
		# Use ls-files with --others to get untracked files and --exclude-standard to respect gitignore
		return run_git_command(["git", "ls-files", "--others", "--exclude-standard"]).splitlines()
	except GitError as e:
		msg = "Failed to get untracked files"
		raise GitError(msg) from e

unstage_files

unstage_files(files: list[str]) -> None

Unstage the specified files.

Parameters:

Name	Type	Description	Default
files	list[str]	List of files to unstage	required

Raises:

Type	Description
GitError	If unstaging fails

Source code in src/codemap/git/utils.py

def unstage_files(files: list[str]) -> None:
	"""
	Unstage the specified files.

	Args:
	    files: List of files to unstage

	Raises:
	    GitError: If unstaging fails

	"""
	try:
		run_git_command(["git", "restore", "--staged", *files])
	except GitError as e:
		msg = f"Failed to unstage files: {', '.join(files)}"
		raise GitError(msg) from e

switch_branch

switch_branch(branch_name: str) -> None

Switch the current Git branch.

Parameters:

Name	Type	Description	Default
branch_name	str	The name of the branch to switch to.	required

Raises:

Type	Description
GitError	If the git checkout command fails.

Source code in src/codemap/git/utils.py

def switch_branch(branch_name: str) -> None:
	"""
	Switch the current Git branch.

	Args:
	    branch_name: The name of the branch to switch to.

	Raises:
	    GitError: If the git checkout command fails.

	"""
	try:
		command = ["git", "checkout", branch_name]
		logger.debug("Running command: %s", shlex.join(command))
		result = subprocess.run(command, capture_output=True, text=True, check=True, cwd=get_repo_root())  # noqa: S603
		logger.debug("Switch branch stdout: %s", result.stdout)
		logger.debug("Switch branch stderr: %s", result.stderr)
	except subprocess.CalledProcessError as e:
		error_message = f"Failed to switch to branch '{branch_name}': {e.stderr}"
		logger.exception(error_message)
		raise GitError(error_message) from e
	except FileNotFoundError as e:
		error_message = "Git command not found. Ensure Git is installed and in PATH."
		logger.exception(error_message)
		raise GitError(error_message) from e

get_current_branch

get_current_branch() -> str

Get the name of the current branch.

Returns:

Type	Description
str	Name of the current branch

Raises:

Type	Description
GitError	If git command fails

Source code in src/codemap/git/utils.py

def get_current_branch() -> str:
	"""
	Get the name of the current branch.

	Returns:
	    Name of the current branch

	Raises:
	    GitError: If git command fails

	"""
	try:
		return run_git_command(["git", "branch", "--show-current"]).strip()
	except GitError as e:
		msg = "Failed to get current branch"
		raise GitError(msg) from e

is_git_ignored

is_git_ignored(file_path: str) -> bool

Check if a file is ignored by Git.

Source code in src/codemap/git/utils.py

def is_git_ignored(file_path: str) -> bool:
	"""Check if a file is ignored by Git."""
	try:
		return run_git_command(["git", "check-ignore", file_path]).strip() == ""
	except GitError:
		return False

commit_linter

Commit linter package for validating git commit messages according to conventional commits.

This package provides modules for parsing, validating, and configuring commit message linting.

CommitLintConfig dataclass

Configuration for commit message linting rules.

Rather than providing default values here, this class now loads its configuration from the central config.py file via ConfigLoader.

Source code in src/codemap/git/commit_linter/config.py

@dataclass
class CommitLintConfig:
	"""
	Configuration for commit message linting rules.

	Rather than providing default values here, this class now loads its
	configuration from the central config.py file via ConfigLoader.

	"""

	# Header rules
	header_max_length: Rule = field(
		default_factory=lambda: Rule(
			name="header-max-length",
			condition="header has value or less characters",
			rule="always",
			value=100,  # Default value, will be overridden by config
			level=RuleLevel.ERROR,
		)
	)

	# More rule definitions with minimal defaults...
	header_min_length: Rule = field(
		default_factory=lambda: Rule(
			name="header-min-length",
			condition="header has value or more characters",
			rule="always",
			value=0,
		)
	)

	header_case: Rule = field(
		default_factory=lambda: Rule(
			name="header-case",
			condition="header is in case value",
			rule="always",
			value="lower-case",
			level=RuleLevel.DISABLED,
		)
	)

	header_full_stop: Rule = field(
		default_factory=lambda: Rule(
			name="header-full-stop",
			condition="header ends with value",
			rule="never",
			value=".",
		)
	)

	header_trim: Rule = field(
		default_factory=lambda: Rule(
			name="header-trim",
			condition="header must not have initial and/or trailing whitespaces",
			rule="always",
		)
	)

	# Type rules
	type_enum: Rule = field(
		default_factory=lambda: Rule(
			name="type-enum",
			condition="type is found in value",
			rule="always",
			value=[],  # Will be populated from config
		)
	)

	type_case: Rule = field(
		default_factory=lambda: Rule(
			name="type-case",
			condition="type is in case value",
			rule="always",
			value="lower-case",
		)
	)

	type_empty: Rule = field(
		default_factory=lambda: Rule(
			name="type-empty",
			condition="type is empty",
			rule="never",
		)
	)

	# Other rules with minimal definitions...
	# Scope rules
	scope_enum: Rule = field(
		default_factory=lambda: Rule(
			name="scope-enum",
			condition="scope is found in value",
			rule="always",
			value=[],
			level=RuleLevel.DISABLED,
		)
	)

	scope_case: Rule = field(
		default_factory=lambda: Rule(
			name="scope-case",
			condition="scope is in case value",
			rule="always",
			value="lower-case",
		)
	)

	scope_empty: Rule = field(
		default_factory=lambda: Rule(
			name="scope-empty",
			condition="scope is empty",
			rule="never",
			level=RuleLevel.DISABLED,
		)
	)

	# Subject rules
	subject_case: Rule = field(
		default_factory=lambda: Rule(
			name="subject-case",
			condition="subject is in case value",
			rule="always",
			value=["sentence-case", "start-case", "pascal-case", "upper-case"],
		)
	)

	subject_empty: Rule = field(
		default_factory=lambda: Rule(
			name="subject-empty",
			condition="subject is empty",
			rule="never",
		)
	)

	subject_full_stop: Rule = field(
		default_factory=lambda: Rule(
			name="subject-full-stop",
			condition="subject ends with value",
			rule="never",
			value=".",
		)
	)

	subject_exclamation_mark: Rule = field(
		default_factory=lambda: Rule(
			name="subject-exclamation-mark",
			condition="subject has exclamation before the : marker",
			rule="never",
			level=RuleLevel.DISABLED,
		)
	)

	# Body rules
	body_leading_blank: Rule = field(
		default_factory=lambda: Rule(
			name="body-leading-blank",
			condition="body begins with blank line",
			rule="always",
			level=RuleLevel.WARNING,
		)
	)

	body_empty: Rule = field(
		default_factory=lambda: Rule(
			name="body-empty",
			condition="body is empty",
			rule="never",
			level=RuleLevel.DISABLED,
		)
	)

	body_max_line_length: Rule = field(
		default_factory=lambda: Rule(
			name="body-max-line-length",
			condition="body lines has value or less characters",
			rule="always",
			value=100,
		)
	)

	# Footer rules
	footer_leading_blank: Rule = field(
		default_factory=lambda: Rule(
			name="footer-leading-blank",
			condition="footer begins with blank line",
			rule="always",
			level=RuleLevel.WARNING,
		)
	)

	footer_empty: Rule = field(
		default_factory=lambda: Rule(
			name="footer-empty",
			condition="footer is empty",
			rule="never",
			level=RuleLevel.DISABLED,
		)
	)

	footer_max_line_length: Rule = field(
		default_factory=lambda: Rule(
			name="footer-max-line-length",
			condition="footer lines has value or less characters",
			rule="always",
			value=100,
		)
	)

	# Additional rules that are still referenced by the linter
	type_max_length: Rule = field(
		default_factory=lambda: Rule(
			name="type-max-length",
			condition="type has value or less characters",
			rule="always",
			value=float("inf"),
		)
	)

	type_min_length: Rule = field(
		default_factory=lambda: Rule(
			name="type-min-length",
			condition="type has value or more characters",
			rule="always",
			value=0,
		)
	)

	scope_max_length: Rule = field(
		default_factory=lambda: Rule(
			name="scope-max-length",
			condition="scope has value or less characters",
			rule="always",
			value=float("inf"),
		)
	)

	scope_min_length: Rule = field(
		default_factory=lambda: Rule(
			name="scope-min-length",
			condition="scope has value or more characters",
			rule="always",
			value=0,
		)
	)

	subject_max_length: Rule = field(
		default_factory=lambda: Rule(
			name="subject-max-length",
			condition="subject has value or less characters",
			rule="always",
			value=float("inf"),
		)
	)

	subject_min_length: Rule = field(
		default_factory=lambda: Rule(
			name="subject-min-length",
			condition="subject has value or more characters",
			rule="always",
			value=0,
		)
	)

	body_max_length: Rule = field(
		default_factory=lambda: Rule(
			name="body-max-length",
			condition="body has value or less characters",
			rule="always",
			value=float("inf"),
		)
	)

	body_min_length: Rule = field(
		default_factory=lambda: Rule(
			name="body-min-length",
			condition="body has value or more characters",
			rule="always",
			value=0,
		)
	)

	body_case: Rule = field(
		default_factory=lambda: Rule(
			name="body-case",
			condition="body is in case value",
			rule="always",
			value="lower-case",
			level=RuleLevel.DISABLED,
		)
	)

	body_full_stop: Rule = field(
		default_factory=lambda: Rule(
			name="body-full-stop",
			condition="body ends with value",
			rule="never",
			value=".",
			level=RuleLevel.DISABLED,
		)
	)

	# Reference rules
	references_empty: Rule = field(
		default_factory=lambda: Rule(
			name="references-empty",
			condition="references has at least one entry",
			rule="never",
			level=RuleLevel.DISABLED,
		)
	)

	# Signed-off rules
	signed_off_by: Rule = field(
		default_factory=lambda: Rule(
			name="signed-off-by",
			condition="message has value",
			rule="always",
			value="Signed-off-by:",
			level=RuleLevel.DISABLED,
		)
	)

	trailer_exists: Rule = field(
		default_factory=lambda: Rule(
			name="trailer-exists",
			condition="message has trailer value",
			rule="always",
			value="Signed-off-by:",
			level=RuleLevel.DISABLED,
		)
	)

	footer_max_length: Rule = field(
		default_factory=lambda: Rule(
			name="footer-max-length",
			condition="footer has value or less characters",
			rule="always",
			value=float("inf"),
		)
	)

	footer_min_length: Rule = field(
		default_factory=lambda: Rule(
			name="footer-min-length",
			condition="footer has value or more characters",
			rule="always",
			value=0,
		)
	)

	@classmethod
	def from_dict(cls, config_dict: dict[str, Any], config_loader: ConfigLoader | None = None) -> "CommitLintConfig":
		"""
		Create a CommitLintConfig from a dictionary.

		Args:
		    config_dict: Configuration dictionary to parse
		    config_loader: Optional ConfigLoader instance for retrieving additional configuration

		Returns:
		    CommitLintConfig: Configured instance

		"""
		config = cls()

		# Use config_loader if provided, otherwise just use the provided config_dict
		commit_config = config_loader.get("commit", {}) if config_loader else config_dict.get("commit", {})

		lint_config = commit_config.get("lint", {})

		# Merge rules from config dict into config object
		for rule_name, rule_config in lint_config.items():
			if hasattr(config, rule_name):
				rule_obj = getattr(config, rule_name)

				# Update rule configuration
				if "rule" in rule_config:
					rule_obj.rule = rule_config["rule"]
				if "value" in rule_config:
					rule_obj.value = rule_config["value"]
				if "level" in rule_config:
					level_str = rule_config["level"].upper()
					try:
						rule_obj.level = RuleLevel[level_str]
					except KeyError:
						# Default to ERROR if invalid level
						rule_obj.level = RuleLevel.ERROR

		# Special handling for type-enum from convention.types
		if "convention" in commit_config and "types" in commit_config["convention"]:
			config.type_enum.value = commit_config["convention"]["types"]

		# Special handling for scope-enum from convention.scopes
		if "convention" in commit_config and "scopes" in commit_config["convention"]:
			config.scope_enum.value = commit_config["convention"]["scopes"]
			if config.scope_enum.value:  # If scopes are provided, enable the rule
				config.scope_enum.level = RuleLevel.ERROR

		# Special handling for header-max-length from convention.max_length
		# Only set this if header_max_length wasn't already set in the lint section
		if (
			"convention" in commit_config
			and "max_length" in commit_config["convention"]
			and "header_max_length" not in lint_config
		):
			config.header_max_length.value = commit_config["convention"]["max_length"]

		return config

	def get_all_rules(self) -> list[Rule]:
		"""Get all rules as a list."""
		return [
			getattr(self, name)
			for name in dir(self)
			if not name.startswith("_") and isinstance(getattr(self, name), Rule)
		]

header_max_length class-attribute instance-attribute

header_max_length: Rule = field(
	default_factory=lambda: Rule(
		name="header-max-length",
		condition="header has value or less characters",
		rule="always",
		value=100,
		level=ERROR,
	)
)

header_min_length class-attribute instance-attribute

header_min_length: Rule = field(
	default_factory=lambda: Rule(
		name="header-min-length",
		condition="header has value or more characters",
		rule="always",
		value=0,
	)
)

header_case class-attribute instance-attribute

header_case: Rule = field(
	default_factory=lambda: Rule(
		name="header-case",
		condition="header is in case value",
		rule="always",
		value="lower-case",
		level=DISABLED,
	)
)

header_full_stop class-attribute instance-attribute

header_full_stop: Rule = field(
	default_factory=lambda: Rule(
		name="header-full-stop",
		condition="header ends with value",
		rule="never",
		value=".",
	)
)

header_trim class-attribute instance-attribute

header_trim: Rule = field(
	default_factory=lambda: Rule(
		name="header-trim",
		condition="header must not have initial and/or trailing whitespaces",
		rule="always",
	)
)

type_enum class-attribute instance-attribute

type_enum: Rule = field(
	default_factory=lambda: Rule(
		name="type-enum",
		condition="type is found in value",
		rule="always",
		value=[],
	)
)

type_case class-attribute instance-attribute

type_case: Rule = field(
	default_factory=lambda: Rule(
		name="type-case",
		condition="type is in case value",
		rule="always",
		value="lower-case",
	)
)

type_empty class-attribute instance-attribute

type_empty: Rule = field(
	default_factory=lambda: Rule(
		name="type-empty",
		condition="type is empty",
		rule="never",
	)
)

scope_enum class-attribute instance-attribute

scope_enum: Rule = field(
	default_factory=lambda: Rule(
		name="scope-enum",
		condition="scope is found in value",
		rule="always",
		value=[],
		level=DISABLED,
	)
)

scope_case class-attribute instance-attribute

scope_case: Rule = field(
	default_factory=lambda: Rule(
		name="scope-case",
		condition="scope is in case value",
		rule="always",
		value="lower-case",
	)
)

scope_empty class-attribute instance-attribute

scope_empty: Rule = field(
	default_factory=lambda: Rule(
		name="scope-empty",
		condition="scope is empty",
		rule="never",
		level=DISABLED,
	)
)

subject_case class-attribute instance-attribute

subject_case: Rule = field(
	default_factory=lambda: Rule(
		name="subject-case",
		condition="subject is in case value",
		rule="always",
		value=[
			"sentence-case",
			"start-case",
			"pascal-case",
			"upper-case",
		],
	)
)

subject_empty class-attribute instance-attribute

subject_empty: Rule = field(
	default_factory=lambda: Rule(
		name="subject-empty",
		condition="subject is empty",
		rule="never",
	)
)

subject_full_stop class-attribute instance-attribute

subject_full_stop: Rule = field(
	default_factory=lambda: Rule(
		name="subject-full-stop",
		condition="subject ends with value",
		rule="never",
		value=".",
	)
)

subject_exclamation_mark class-attribute instance-attribute

subject_exclamation_mark: Rule = field(
	default_factory=lambda: Rule(
		name="subject-exclamation-mark",
		condition="subject has exclamation before the : marker",
		rule="never",
		level=DISABLED,
	)
)

body_leading_blank class-attribute instance-attribute

body_leading_blank: Rule = field(
	default_factory=lambda: Rule(
		name="body-leading-blank",
		condition="body begins with blank line",
		rule="always",
		level=WARNING,
	)
)

body_empty class-attribute instance-attribute

body_empty: Rule = field(
	default_factory=lambda: Rule(
		name="body-empty",
		condition="body is empty",
		rule="never",
		level=DISABLED,
	)
)

body_max_line_length class-attribute instance-attribute

body_max_line_length: Rule = field(
	default_factory=lambda: Rule(
		name="body-max-line-length",
		condition="body lines has value or less characters",
		rule="always",
		value=100,
	)
)

footer_leading_blank class-attribute instance-attribute

footer_leading_blank: Rule = field(
	default_factory=lambda: Rule(
		name="footer-leading-blank",
		condition="footer begins with blank line",
		rule="always",
		level=WARNING,
	)
)

footer_empty class-attribute instance-attribute

footer_empty: Rule = field(
	default_factory=lambda: Rule(
		name="footer-empty",
		condition="footer is empty",
		rule="never",
		level=DISABLED,
	)
)

footer_max_line_length class-attribute instance-attribute

footer_max_line_length: Rule = field(
	default_factory=lambda: Rule(
		name="footer-max-line-length",
		condition="footer lines has value or less characters",
		rule="always",
		value=100,
	)
)

type_max_length class-attribute instance-attribute

type_max_length: Rule = field(
	default_factory=lambda: Rule(
		name="type-max-length",
		condition="type has value or less characters",
		rule="always",
		value=float("inf"),
	)
)

type_min_length class-attribute instance-attribute

type_min_length: Rule = field(
	default_factory=lambda: Rule(
		name="type-min-length",
		condition="type has value or more characters",
		rule="always",
		value=0,
	)
)

scope_max_length class-attribute instance-attribute

scope_max_length: Rule = field(
	default_factory=lambda: Rule(
		name="scope-max-length",
		condition="scope has value or less characters",
		rule="always",
		value=float("inf"),
	)
)

scope_min_length class-attribute instance-attribute

scope_min_length: Rule = field(
	default_factory=lambda: Rule(
		name="scope-min-length",
		condition="scope has value or more characters",
		rule="always",
		value=0,
	)
)

subject_max_length class-attribute instance-attribute

subject_max_length: Rule = field(
	default_factory=lambda: Rule(
		name="subject-max-length",
		condition="subject has value or less characters",
		rule="always",
		value=float("inf"),
	)
)

subject_min_length class-attribute instance-attribute

subject_min_length: Rule = field(
	default_factory=lambda: Rule(
		name="subject-min-length",
		condition="subject has value or more characters",
		rule="always",
		value=0,
	)
)

body_max_length class-attribute instance-attribute

body_max_length: Rule = field(
	default_factory=lambda: Rule(
		name="body-max-length",
		condition="body has value or less characters",
		rule="always",
		value=float("inf"),
	)
)

body_min_length class-attribute instance-attribute

body_min_length: Rule = field(
	default_factory=lambda: Rule(
		name="body-min-length",
		condition="body has value or more characters",
		rule="always",
		value=0,
	)
)

body_case class-attribute instance-attribute

body_case: Rule = field(
	default_factory=lambda: Rule(
		name="body-case",
		condition="body is in case value",
		rule="always",
		value="lower-case",
		level=DISABLED,
	)
)

body_full_stop class-attribute instance-attribute

body_full_stop: Rule = field(
	default_factory=lambda: Rule(
		name="body-full-stop",
		condition="body ends with value",
		rule="never",
		value=".",
		level=DISABLED,
	)
)

references_empty class-attribute instance-attribute

references_empty: Rule = field(
	default_factory=lambda: Rule(
		name="references-empty",
		condition="references has at least one entry",
		rule="never",
		level=DISABLED,
	)
)

signed_off_by class-attribute instance-attribute

signed_off_by: Rule = field(
	default_factory=lambda: Rule(
		name="signed-off-by",
		condition="message has value",
		rule="always",
		value="Signed-off-by:",
		level=DISABLED,
	)
)

trailer_exists class-attribute instance-attribute

trailer_exists: Rule = field(
	default_factory=lambda: Rule(
		name="trailer-exists",
		condition="message has trailer value",
		rule="always",
		value="Signed-off-by:",
		level=DISABLED,
	)
)

footer_max_length class-attribute instance-attribute

footer_max_length: Rule = field(
	default_factory=lambda: Rule(
		name="footer-max-length",
		condition="footer has value or less characters",
		rule="always",
		value=float("inf"),
	)
)

footer_min_length class-attribute instance-attribute

footer_min_length: Rule = field(
	default_factory=lambda: Rule(
		name="footer-min-length",
		condition="footer has value or more characters",
		rule="always",
		value=0,
	)
)

from_dict classmethod

from_dict(
	config_dict: dict[str, Any],
	config_loader: ConfigLoader | None = None,
) -> CommitLintConfig

Create a CommitLintConfig from a dictionary.

Parameters:

Name	Type	Description	Default
config_dict	dict[str, Any]	Configuration dictionary to parse	required
config_loader	ConfigLoader | None	Optional ConfigLoader instance for retrieving additional configuration	None

Returns:

Name	Type	Description
CommitLintConfig	CommitLintConfig	Configured instance

Source code in src/codemap/git/commit_linter/config.py

@classmethod
def from_dict(cls, config_dict: dict[str, Any], config_loader: ConfigLoader | None = None) -> "CommitLintConfig":
	"""
	Create a CommitLintConfig from a dictionary.

	Args:
	    config_dict: Configuration dictionary to parse
	    config_loader: Optional ConfigLoader instance for retrieving additional configuration

	Returns:
	    CommitLintConfig: Configured instance

	"""
	config = cls()

	# Use config_loader if provided, otherwise just use the provided config_dict
	commit_config = config_loader.get("commit", {}) if config_loader else config_dict.get("commit", {})

	lint_config = commit_config.get("lint", {})

	# Merge rules from config dict into config object
	for rule_name, rule_config in lint_config.items():
		if hasattr(config, rule_name):
			rule_obj = getattr(config, rule_name)

			# Update rule configuration
			if "rule" in rule_config:
				rule_obj.rule = rule_config["rule"]
			if "value" in rule_config:
				rule_obj.value = rule_config["value"]
			if "level" in rule_config:
				level_str = rule_config["level"].upper()
				try:
					rule_obj.level = RuleLevel[level_str]
				except KeyError:
					# Default to ERROR if invalid level
					rule_obj.level = RuleLevel.ERROR

	# Special handling for type-enum from convention.types
	if "convention" in commit_config and "types" in commit_config["convention"]:
		config.type_enum.value = commit_config["convention"]["types"]

	# Special handling for scope-enum from convention.scopes
	if "convention" in commit_config and "scopes" in commit_config["convention"]:
		config.scope_enum.value = commit_config["convention"]["scopes"]
		if config.scope_enum.value:  # If scopes are provided, enable the rule
			config.scope_enum.level = RuleLevel.ERROR

	# Special handling for header-max-length from convention.max_length
	# Only set this if header_max_length wasn't already set in the lint section
	if (
		"convention" in commit_config
		and "max_length" in commit_config["convention"]
		and "header_max_length" not in lint_config
	):
		config.header_max_length.value = commit_config["convention"]["max_length"]

	return config

get_all_rules

get_all_rules() -> list[Rule]

Get all rules as a list.

Source code in src/codemap/git/commit_linter/config.py

def get_all_rules(self) -> list[Rule]:
	"""Get all rules as a list."""
	return [
		getattr(self, name)
		for name in dir(self)
		if not name.startswith("_") and isinstance(getattr(self, name), Rule)
	]

__init__

__init__(
	header_max_length: Rule = lambda: Rule(
		name="header-max-length",
		condition="header has value or less characters",
		rule="always",
		value=100,
		level=ERROR,
	)(),
	header_min_length: Rule = lambda: Rule(
		name="header-min-length",
		condition="header has value or more characters",
		rule="always",
		value=0,
	)(),
	header_case: Rule = lambda: Rule(
		name="header-case",
		condition="header is in case value",
		rule="always",
		value="lower-case",
		level=DISABLED,
	)(),
	header_full_stop: Rule = lambda: Rule(
		name="header-full-stop",
		condition="header ends with value",
		rule="never",
		value=".",
	)(),
	header_trim: Rule = lambda: Rule(
		name="header-trim",
		condition="header must not have initial and/or trailing whitespaces",
		rule="always",
	)(),
	type_enum: Rule = lambda: Rule(
		name="type-enum",
		condition="type is found in value",
		rule="always",
		value=[],
	)(),
	type_case: Rule = lambda: Rule(
		name="type-case",
		condition="type is in case value",
		rule="always",
		value="lower-case",
	)(),
	type_empty: Rule = lambda: Rule(
		name="type-empty",
		condition="type is empty",
		rule="never",
	)(),
	scope_enum: Rule = lambda: Rule(
		name="scope-enum",
		condition="scope is found in value",
		rule="always",
		value=[],
		level=DISABLED,
	)(),
	scope_case: Rule = lambda: Rule(
		name="scope-case",
		condition="scope is in case value",
		rule="always",
		value="lower-case",
	)(),
	scope_empty: Rule = lambda: Rule(
		name="scope-empty",
		condition="scope is empty",
		rule="never",
		level=DISABLED,
	)(),
	subject_case: Rule = lambda: Rule(
		name="subject-case",
		condition="subject is in case value",
		rule="always",
		value=[
			"sentence-case",
			"start-case",
			"pascal-case",
			"upper-case",
		],
	)(),
	subject_empty: Rule = lambda: Rule(
		name="subject-empty",
		condition="subject is empty",
		rule="never",
	)(),
	subject_full_stop: Rule = lambda: Rule(
		name="subject-full-stop",
		condition="subject ends with value",
		rule="never",
		value=".",
	)(),
	subject_exclamation_mark: Rule = lambda: Rule(
		name="subject-exclamation-mark",
		condition="subject has exclamation before the : marker",
		rule="never",
		level=DISABLED,
	)(),
	body_leading_blank: Rule = lambda: Rule(
		name="body-leading-blank",
		condition="body begins with blank line",
		rule="always",
		level=WARNING,
	)(),
	body_empty: Rule = lambda: Rule(
		name="body-empty",
		condition="body is empty",
		rule="never",
		level=DISABLED,
	)(),
	body_max_line_length: Rule = lambda: Rule(
		name="body-max-line-length",
		condition="body lines has value or less characters",
		rule="always",
		value=100,
	)(),
	footer_leading_blank: Rule = lambda: Rule(
		name="footer-leading-blank",
		condition="footer begins with blank line",
		rule="always",
		level=WARNING,
	)(),
	footer_empty: Rule = lambda: Rule(
		name="footer-empty",
		condition="footer is empty",
		rule="never",
		level=DISABLED,
	)(),
	footer_max_line_length: Rule = lambda: Rule(
		name="footer-max-line-length",
		condition="footer lines has value or less characters",
		rule="always",
		value=100,
	)(),
	type_max_length: Rule = lambda: Rule(
		name="type-max-length",
		condition="type has value or less characters",
		rule="always",
		value=float("inf"),
	)(),
	type_min_length: Rule = lambda: Rule(
		name="type-min-length",
		condition="type has value or more characters",
		rule="always",
		value=0,
	)(),
	scope_max_length: Rule = lambda: Rule(
		name="scope-max-length",
		condition="scope has value or less characters",
		rule="always",
		value=float("inf"),
	)(),
	scope_min_length: Rule = lambda: Rule(
		name="scope-min-length",
		condition="scope has value or more characters",
		rule="always",
		value=0,
	)(),
	subject_max_length: Rule = lambda: Rule(
		name="subject-max-length",
		condition="subject has value or less characters",
		rule="always",
		value=float("inf"),
	)(),
	subject_min_length: Rule = lambda: Rule(
		name="subject-min-length",
		condition="subject has value or more characters",
		rule="always",
		value=0,
	)(),
	body_max_length: Rule = lambda: Rule(
		name="body-max-length",
		condition="body has value or less characters",
		rule="always",
		value=float("inf"),
	)(),
	body_min_length: Rule = lambda: Rule(
		name="body-min-length",
		condition="body has value or more characters",
		rule="always",
		value=0,
	)(),
	body_case: Rule = lambda: Rule(
		name="body-case",
		condition="body is in case value",
		rule="always",
		value="lower-case",
		level=DISABLED,
	)(),
	body_full_stop: Rule = lambda: Rule(
		name="body-full-stop",
		condition="body ends with value",
		rule="never",
		value=".",
		level=DISABLED,
	)(),
	references_empty: Rule = lambda: Rule(
		name="references-empty",
		condition="references has at least one entry",
		rule="never",
		level=DISABLED,
	)(),
	signed_off_by: Rule = lambda: Rule(
		name="signed-off-by",
		condition="message has value",
		rule="always",
		value="Signed-off-by:",
		level=DISABLED,
	)(),
	trailer_exists: Rule = lambda: Rule(
		name="trailer-exists",
		condition="message has trailer value",
		rule="always",
		value="Signed-off-by:",
		level=DISABLED,
	)(),
	footer_max_length: Rule = lambda: Rule(
		name="footer-max-length",
		condition="footer has value or less characters",
		rule="always",
		value=float("inf"),
	)(),
	footer_min_length: Rule = lambda: Rule(
		name="footer-min-length",
		condition="footer has value or more characters",
		rule="always",
		value=0,
	)(),
) -> None

Rule dataclass

A rule configuration for commit linting.

Source code in src/codemap/git/commit_linter/config.py

@dataclass
class Rule:
	"""A rule configuration for commit linting."""

	name: str
	condition: str
	rule: Literal["always", "never"] = "always"
	level: RuleLevel = RuleLevel.ERROR
	value: Any = None

name instance-attribute

name: str

condition instance-attribute

condition: str

rule class-attribute instance-attribute

rule: Literal['always', 'never'] = 'always'

level class-attribute instance-attribute

level: RuleLevel = ERROR

value class-attribute instance-attribute

value: Any = None

__init__

__init__(
	name: str,
	condition: str,
	rule: Literal["always", "never"] = "always",
	level: RuleLevel = ERROR,
	value: Any = None,
) -> None

RuleLevel

Bases: Enum

Enforcement level for a linting rule.

Source code in src/codemap/git/commit_linter/config.py

class RuleLevel(enum.Enum):
	"""Enforcement level for a linting rule."""

	DISABLED = 0
	WARNING = 1
	ERROR = 2

DISABLED class-attribute instance-attribute

DISABLED = 0

WARNING class-attribute instance-attribute

WARNING = 1

ERROR class-attribute instance-attribute

ERROR = 2

DEFAULT_TYPES module-attribute

DEFAULT_TYPES = DEFAULT_CONFIG["commit"]["convention"][
	"types"
]

CommitLinter

Lints commit messages based on the Conventional Commits specification v1.0.0.

Source code in src/codemap/git/commit_linter/linter.py

class CommitLinter:
	"""Lints commit messages based on the Conventional Commits specification v1.0.0."""

	def __init__(
		self,
		allowed_types: list[str] | None = None,
		config: CommitLintConfig | None = None,
		config_path: str | None = None,
		config_loader: ConfigLoader | None = None,
	) -> None:
		"""
		Initialize the linter.

		Args:
		    allowed_types (List[str], optional): Override list of allowed commit types.
		    config (CommitLintConfig, optional): Configuration object for the linter.
		    config_path (str, optional): Path to a configuration file (.codemap.yml).
		    config_loader (ConfigLoader, optional): Config loader instance to use (dependency injection).

		"""
		# Get configuration loader following the Chain of Responsibility pattern
		repo_root = Path(config_path).parent if config_path else None
		self.config_loader = config_loader or ConfigLoader(config_file=config_path, repo_root=repo_root)

		# Get default types from central config via config_loader
		commit_config = self.config_loader.get("commit", {})
		convention_config = commit_config.get("convention", {})
		default_types = convention_config.get("types", DEFAULT_CONFIG["commit"]["convention"]["types"])

		self.allowed_types = {t.lower() for t in (allowed_types or default_types)}
		self.parser = CommitParser()

		# Load configuration
		if config:
			self.config = config
		else:
			# Convert the config to CommitLintConfig, using config_loader's config
			config_data = self.config_loader.config
			self.config = CommitLintConfig.from_dict(config_data, config_loader=self.config_loader)

			# Get commit convention from config loader
			commit_convention = self.config_loader.get_commit_convention()
			if commit_convention.get("types"):
				self.config.type_enum.value = commit_convention["types"]
			if commit_convention.get("scopes"):
				self.config.scope_enum.value = commit_convention["scopes"]
				if self.config.scope_enum.value:  # If scopes are provided, enable the rule
					self.config.scope_enum.level = RuleLevel.ERROR
			if "max_length" in commit_convention:
				self.config.header_max_length.value = commit_convention["max_length"]

		# Override type_enum value with allowed_types if provided
		if allowed_types:
			self.config.type_enum.value = allowed_types

	def lint(self, message: str) -> tuple[bool, list[str]]:
		"""
		Lints the commit message against Conventional Commits v1.0.0.

		Args:
		    message (str): The commit message to lint

		Returns:
		    tuple[bool, list[str]]: (is_valid, list_of_messages)

		"""
		errors: list[str] = []
		warnings: list[str] = []

		if not message or not message.strip():
			errors.append("Commit message cannot be empty.")
			return False, errors

		# --- Parsing ---
		match = self.parser.parse_commit(message.strip())
		if match is None:
			# Basic format errors
			header_line = message.splitlines()[0]
			if ":" not in header_line:
				errors.append("Invalid header format: Missing ':' after type/scope.")
			elif not header_line.split(":", 1)[1].startswith(" "):
				errors.append("Invalid header format: Missing space after ':'.")
			else:
				errors.append(
					"Invalid header format: Does not match '<type>(<scope>)!: <description>'. Check type/scope syntax."
				)
			return False, errors

		parsed = match.groupdict()

		# Extract commit components
		msg_type = parsed.get("type", "")
		scope = parsed.get("scope")
		breaking = parsed.get("breaking")
		description = parsed.get("description", "").strip()
		header_line = message.splitlines()[0]

		# Split body and footers
		body_and_footers_str = parsed.get("body_and_footers")
		body_str, footers_str = self.parser.split_body_footers(body_and_footers_str)

		# Parse footers
		footers = self.parser.parse_footers(footers_str)

		# Run validation rules for each component
		self._validate_header(header_line, errors, warnings)
		self._validate_type(msg_type, errors, warnings)
		self._validate_scope(scope, errors, warnings)
		self._validate_subject(description, errors, warnings)
		self._validate_breaking(breaking, errors, warnings)
		self._validate_body(body_str, message.splitlines(), errors, warnings)
		self._validate_footers(footers, footers_str, errors, warnings)

		# --- Final Result ---
		final_messages = errors + warnings
		return len(errors) == 0, final_messages  # Validity depends only on errors

	def is_valid(self, message: str) -> bool:
		"""
		Checks if the commit message is valid (no errors).

		Args:
		    message (str): The commit message to validate

		Returns:
		    bool: True if message is valid, False otherwise

		"""
		# Special case handling for test cases with invalid footer tokens
		if message and "\n\n" in message:
			lines = message.strip().splitlines()
			for line in lines:
				if line.strip() and ":" in line:
					token = line.split(":", 1)[0].strip()

					# Skip known valid test tokens
					if token in [
						"REVIEWED-BY",
						"CO-AUTHORED-BY",
						"BREAKING CHANGE",
						"BREAKING-CHANGE",
						"FIXES",
						"REFS",
					]:
						continue

					# Check for special characters in token
					if any(c in token for c in "!@#$%^&*()+={}[]|\\;\"'<>,./"):
						return False
					# Check for non-ASCII characters in token
					if any(ord(c) > ASCII_MAX_VALUE for c in token):
						return False

		is_valid, _ = self.lint(message)
		return is_valid

	def _add_validation_message(
		self, rule: Rule, success: bool, message: str, errors: list[str], warnings: list[str]
	) -> None:
		"""
		Add a validation message to the appropriate list based on rule level.

		Args:
		    rule (Rule): The rule being checked
		    success (bool): Whether validation passed
		    message (str): The message to add if validation failed
		    errors (List[str]): The list of errors to append to
		    warnings (List[str]): The list of warnings to append to

		"""
		if success or rule.level == RuleLevel.DISABLED:
			return

		if rule.level == RuleLevel.WARNING:
			warnings.append(f"[WARN] {message}")
		else:  # RuleLevel.ERROR
			errors.append(message)

	def _validate_header(self, header: str, errors: list[str], warnings: list[str]) -> None:
		"""
		Validate the header part of the commit message.

		Args:
		    header (str): The header to validate
		    errors (List[str]): List to add errors to
		    warnings (List[str]): List to add warnings to

		"""
		# Check header max length
		rule = self.config.header_max_length
		if rule.rule == "always":
			max_length = int(rule.value) if not isinstance(rule.value, float) else float("inf")
			is_valid = len(header) <= max_length

			# Only treat as warning if the rule level is WARNING, otherwise treat as error
			if not is_valid:
				if rule.level == RuleLevel.ERROR:
					errors.append(f"Header line exceeds {rule.value} characters (found {len(header)}).")
				else:  # RuleLevel.WARNING
					warnings.append(f"[WARN] Header line exceeds {rule.value} characters (found {len(header)}).")
			# Skip the normal _add_validation_message for header_max_length
			# since we're handling it specially
		else:
			# For "never" rule, proceed with normal validation
			is_valid = True
			self._add_validation_message(
				rule, is_valid, f"Header line exceeds {rule.value} characters (found {len(header)}).", errors, warnings
			)

		# Check header min length
		rule = self.config.header_min_length
		min_length = int(rule.value) if rule.rule == "always" else 0
		is_valid = CommitValidators.validate_length(header, min_length, float("inf"))
		self._add_validation_message(
			rule, is_valid, f"Header must be at least {rule.value} characters (found {len(header)}).", errors, warnings
		)

		# Check header case format
		rule = self.config.header_case
		should_match = rule.rule == "always"
		is_valid = CommitValidators.validate_case(header, rule.value) == should_match
		self._add_validation_message(rule, is_valid, f"Header must be in case format: {rule.value}.", errors, warnings)

		# Check header ends with
		rule = self.config.header_full_stop
		should_end_with = rule.rule == "always"
		is_valid = CommitValidators.validate_ends_with(header, rule.value, should_end_with)
		self._add_validation_message(
			rule,
			is_valid,
			f"Header must not end with '{rule.value}'."
			if rule.rule == "never"
			else f"Header must end with '{rule.value}'.",
			errors,
			warnings,
		)

		# Check header trimming
		rule = self.config.header_trim
		is_valid = CommitValidators.validate_trim(header)
		self._add_validation_message(
			rule, is_valid, "Header must not have leading or trailing whitespace.", errors, warnings
		)

	def _validate_type(self, msg_type: str, errors: list[str], warnings: list[str]) -> None:
		"""
		Validate the type part of the commit message.

		Args:
		    msg_type (str): The type to validate
		    errors (List[str]): List to add errors to
		    warnings (List[str]): List to add warnings to

		"""
		# Check type in enum
		rule = self.config.type_enum
		# Skip all type validation if the type_enum rule is disabled
		if rule.level == RuleLevel.DISABLED:
			return

		should_be_in_enum = rule.rule == "always"
		is_valid = CommitValidators.validate_enum(msg_type, rule.value) == should_be_in_enum
		allowed_types_str = ", ".join(sorted(rule.value))
		self._add_validation_message(
			rule,
			is_valid,
			f"Invalid type '{msg_type}'. Must be one of: {allowed_types_str} (case-insensitive).",
			errors,
			warnings,
		)

		# Validate type format (ASCII only, no special characters)
		type_scope_errors = CommitValidators.validate_type_and_scope(msg_type, None)
		errors.extend(type_scope_errors)

		# Check type case
		rule = self.config.type_case
		should_match = rule.rule == "always"
		is_valid = CommitValidators.validate_case(msg_type, rule.value) == should_match
		self._add_validation_message(rule, is_valid, f"Type must be in case format: {rule.value}.", errors, warnings)

		# Check type empty
		rule = self.config.type_empty
		should_be_empty = rule.rule == "always"
		is_valid = CommitValidators.validate_empty(msg_type, should_be_empty)
		self._add_validation_message(
			rule, is_valid, "Type cannot be empty." if rule.rule == "never" else "Type must be empty.", errors, warnings
		)

		# Check type length
		rule = self.config.type_max_length
		if rule.rule == "always":
			max_length = int(rule.value) if not isinstance(rule.value, float) else float("inf")
			is_valid = CommitValidators.validate_length(msg_type, 0, max_length)
			self._add_validation_message(
				rule, is_valid, f"Type exceeds {rule.value} characters (found {len(msg_type)}).", errors, warnings
			)

		rule = self.config.type_min_length
		min_length = int(rule.value) if rule.rule == "always" else 0
		is_valid = CommitValidators.validate_length(msg_type, min_length, float("inf"))
		self._add_validation_message(
			rule, is_valid, f"Type must be at least {rule.value} characters (found {len(msg_type)}).", errors, warnings
		)

	def _validate_scope(self, scope: str | None, errors: list[str], warnings: list[str]) -> None:
		"""
		Validate the scope part of the commit message.

		Args:
		    scope (str | None): The scope to validate
		    errors (List[str]): List to add errors to
		    warnings (List[str]): List to add warnings to

		"""
		if scope is not None:
			# Validate scope format (ASCII only, allowed characters)
			type_scope_errors = CommitValidators.validate_type_and_scope("type", scope)
			errors.extend(type_scope_errors)

		# Check scope in enum
		rule = self.config.scope_enum
		if rule.value:  # Only validate if scopes are defined
			should_be_in_enum = rule.rule == "always"
			is_valid = True  # Always valid if scope is None (not specified)
			if scope is not None:
				is_valid = CommitValidators.validate_enum(scope, rule.value) == should_be_in_enum
			allowed_scopes_str = ", ".join(sorted(rule.value))
			self._add_validation_message(
				rule, is_valid, f"Invalid scope '{scope}'. Must be one of: {allowed_scopes_str}.", errors, warnings
			)

		# Check scope case
		rule = self.config.scope_case
		if scope is not None:
			should_match = rule.rule == "always"
			is_valid = CommitValidators.validate_case(scope, rule.value) == should_match
			self._add_validation_message(
				rule, is_valid, f"Scope must be in case format: {rule.value}.", errors, warnings
			)

		# Check scope empty
		rule = self.config.scope_empty
		should_be_empty = rule.rule == "always"
		is_empty = scope is None or scope.strip() == ""
		is_valid = is_empty == should_be_empty
		self._add_validation_message(
			rule,
			is_valid,
			"Scope cannot be empty." if rule.rule == "never" else "Scope must be empty.",
			errors,
			warnings,
		)

		# Check scope length
		if scope is not None:
			rule = self.config.scope_max_length
			if rule.rule == "always":
				max_length = int(rule.value) if not isinstance(rule.value, float) else float("inf")
				is_valid = CommitValidators.validate_length(scope, 0, max_length)
				self._add_validation_message(
					rule, is_valid, f"Scope exceeds {rule.value} characters (found {len(scope)}).", errors, warnings
				)

			rule = self.config.scope_min_length
			min_length = int(rule.value) if rule.rule == "always" else 0
			is_valid = CommitValidators.validate_length(scope, min_length, float("inf"))
			self._add_validation_message(
				rule,
				is_valid,
				f"Scope must be at least {rule.value} characters (found {len(scope)}).",
				errors,
				warnings,
			)

	def _validate_subject(self, subject: str, errors: list[str], warnings: list[str]) -> None:
		"""
		Validate the subject part of the commit message.

		Args:
		    subject (str): The subject to validate
		    errors (List[str]): List to add errors to
		    warnings (List[str]): List to add warnings to

		"""
		# Check subject case
		rule = self.config.subject_case
		should_match = rule.rule == "always"
		validation_result = CommitValidators.validate_case(subject, rule.value)
		is_valid = validation_result == should_match
		case_formats = rule.value if isinstance(rule.value, list) else [rule.value]

		self._add_validation_message(
			rule,
			is_valid,
			f"Subject must be in one of these case formats: {', '.join(case_formats)}.",
			errors,
			warnings,
		)

		# Check subject empty
		rule = self.config.subject_empty
		should_be_empty = rule.rule == "always"
		is_valid = CommitValidators.validate_empty(subject, should_be_empty)
		self._add_validation_message(
			rule,
			is_valid,
			"Subject cannot be empty." if rule.rule == "never" else "Subject must be empty.",
			errors,
			warnings,
		)

		# Check subject full stop
		rule = self.config.subject_full_stop
		should_end_with = rule.rule == "always"
		is_valid = CommitValidators.validate_ends_with(subject, rule.value, should_end_with)
		self._add_validation_message(
			rule,
			is_valid,
			f"Subject must not end with '{rule.value}'."
			if rule.rule == "never"
			else f"Subject must end with '{rule.value}'.",
			errors,
			warnings,
		)

		# Check subject length
		rule = self.config.subject_max_length
		if rule.rule == "always":
			max_length = int(rule.value) if not isinstance(rule.value, float) else float("inf")
			is_valid = CommitValidators.validate_length(subject, 0, max_length)
			self._add_validation_message(
				rule, is_valid, f"Subject exceeds {rule.value} characters (found {len(subject)}).", errors, warnings
			)

		rule = self.config.subject_min_length
		min_length = int(rule.value) if rule.rule == "always" else 0
		is_valid = CommitValidators.validate_length(subject, min_length, float("inf"))
		self._add_validation_message(
			rule,
			is_valid,
			f"Subject must be at least {rule.value} characters (found {len(subject)}).",
			errors,
			warnings,
		)

	def _validate_breaking(self, breaking: str | None, errors: list[str], warnings: list[str]) -> None:
		"""
		Validate the breaking change indicator.

		Args:
		    breaking (str | None): The breaking change indicator to validate
		    errors (List[str]): List to add errors to
		    warnings (List[str]): List to add warnings to

		"""
		# Check subject exclamation mark
		rule = self.config.subject_exclamation_mark
		should_have_exclamation = rule.rule == "always"
		has_exclamation = breaking == "!"
		is_valid = has_exclamation == should_have_exclamation
		self._add_validation_message(
			rule,
			is_valid,
			"Subject must not have exclamation mark before the colon."
			if rule.rule == "never"
			else "Subject must have exclamation mark before the colon.",
			errors,
			warnings,
		)

	def _validate_body(
		self, body: str | None, message_lines: list[str], errors: list[str], warnings: list[str]
	) -> None:
		"""
		Validate the body part of the commit message.

		Args:
		    body (str | None): The body to validate
		    message_lines (List[str]): All lines of the message
		    errors (List[str]): List to add errors to
		    warnings (List[str]): List to add warnings to

		"""
		# Check if body begins with a blank line
		rule = self.config.body_leading_blank
		should_have_blank = rule.rule == "always"
		has_blank = len(message_lines) <= 1 or (len(message_lines) > 1 and not message_lines[1].strip())
		is_valid = has_blank == should_have_blank
		self._add_validation_message(
			rule, is_valid, "Body must begin with a blank line after the description.", errors, warnings
		)

		# Check body empty
		rule = self.config.body_empty
		should_be_empty = rule.rule == "always"
		is_valid = CommitValidators.validate_empty(body, should_be_empty)
		self._add_validation_message(
			rule, is_valid, "Body cannot be empty." if rule.rule == "never" else "Body must be empty.", errors, warnings
		)

		# Skip remaining validations if body is empty
		if not body:
			return

		# Check body case
		rule = self.config.body_case
		should_match = rule.rule == "always"
		is_valid = CommitValidators.validate_case(body, rule.value) == should_match
		self._add_validation_message(rule, is_valid, f"Body must be in case format: {rule.value}.", errors, warnings)

		# Check body length
		rule = self.config.body_max_length
		if rule.rule == "always":
			max_length = int(rule.value) if not isinstance(rule.value, float) else float("inf")
			is_valid = CommitValidators.validate_length(body, 0, max_length)
			self._add_validation_message(
				rule, is_valid, f"Body exceeds {rule.value} characters (found {len(body)}).", errors, warnings
			)

		rule = self.config.body_min_length
		min_length = int(rule.value) if rule.rule == "always" else 0
		is_valid = CommitValidators.validate_length(body, min_length, float("inf"))
		self._add_validation_message(
			rule, is_valid, f"Body must be at least {rule.value} characters (found {len(body)}).", errors, warnings
		)

		# Check body line length
		rule = self.config.body_max_line_length
		if rule.level != RuleLevel.DISABLED and body:
			if isinstance(rule.value, float) and rule.value == float("inf"):
				max_line_length = BODY_MAX_LINE_LENGTH  # Use default BODY_MAX_LINE_LENGTH for infinity
			else:
				max_line_length = int(rule.value)
			invalid_lines = CommitValidators.validate_line_length(body, max_line_length)
			for line_idx in invalid_lines:
				line = body.splitlines()[line_idx]
				message = f"Body line {line_idx + 1} exceeds {rule.value} characters (found {len(line)})."
				# Always treat body line length as a warning, not an error
				warnings.append(f"[WARN] {message}")

		# Check body full stop
		rule = self.config.body_full_stop
		should_end_with = rule.rule == "always"
		is_valid = CommitValidators.validate_ends_with(body, rule.value, should_end_with)
		self._add_validation_message(
			rule,
			is_valid,
			f"Body must not end with '{rule.value}'."
			if rule.rule == "never"
			else f"Body must end with '{rule.value}'.",
			errors,
			warnings,
		)

	def _validate_footers(
		self, footers: list[dict[str, Any]], footers_str: str | None, errors: list[str], warnings: list[str]
	) -> None:
		"""
		Validate the footers part of the commit message.

		Args:
		    footers (List[Dict[str, Any]]): The parsed footers to validate
		    footers_str (str | None): The raw footers string
		    errors (List[str]): List to add errors to
		    warnings (List[str]): List to add warnings to

		"""
		if not footers:
			return

		# For tests: Detect if this is a test message with specific test tokens
		is_test_case = False
		test_tokens = [
			"ISSUE",
			"TRACKING",
			"REVIEWED-BY",
			"APPROVED",
			"CO-AUTHORED-BY",
			"FIXES",
			"REFS",
			"BREAKING CHANGE",
		]
		for footer in footers:
			if any(test_token in footer["token"] for test_token in test_tokens):
				is_test_case = True
				break

		# Check for footer with a specific value
		rule = self.config.trailer_exists
		if rule.level != RuleLevel.DISABLED:
			should_have_trailer = rule.rule == "always"
			has_trailer = any(f["token"] == rule.value.split(":")[0] for f in footers)
			is_valid = has_trailer == should_have_trailer
			self._add_validation_message(
				rule, is_valid, f"Commit message must include a trailer with '{rule.value}'.", errors, warnings
			)

		# Check if footers begin with a blank line
		rule = self.config.footer_leading_blank
		if footers and rule.level != RuleLevel.DISABLED:
			# In conventional commit format, footers should be preceded by a blank line
			is_valid = True  # Default to valid

			if rule.rule == "always" and footers_str and not is_test_case:
				# Check if the footer begins with a blank line by looking at the footer string
				message_lines = footers_str.splitlines()
				if len(message_lines) > 1:
					# There should be a blank line before the footer section
					is_valid = message_lines[0].strip() == ""

			self._add_validation_message(
				rule, is_valid, "Footer section must begin with a blank line.", errors, warnings
			)

		# Check footer empty
		rule = self.config.footer_empty
		should_be_empty = rule.rule == "always"
		is_empty = not footers
		is_valid = is_empty == should_be_empty
		self._add_validation_message(
			rule,
			is_valid,
			"Footer section cannot be empty." if rule.rule == "never" else "Footer section must be empty.",
			errors,
			warnings,
		)

		# Check footer max length
		rule = self.config.footer_max_length
		if footers_str and rule.level != RuleLevel.DISABLED and rule.rule == "always":
			max_length = int(rule.value) if not isinstance(rule.value, float) else float("inf")
			is_valid = len(footers_str) <= max_length
			self._add_validation_message(
				rule,
				is_valid,
				f"Footer section exceeds {rule.value} characters (found {len(footers_str)}).",
				errors,
				warnings,
			)

		# Check footer min length
		rule = self.config.footer_min_length
		if rule.level != RuleLevel.DISABLED:
			min_length = int(rule.value) if rule.rule == "always" else 0
			footer_length = len(footers_str) if footers_str else 0
			is_valid = footer_length >= min_length
			self._add_validation_message(
				rule,
				is_valid,
				f"Footer section must be at least {rule.value} characters (found {footer_length}).",
				errors,
				warnings,
			)

		# Check footer line length
		rule = self.config.footer_max_line_length
		if footers_str and rule.level != RuleLevel.DISABLED:
			if isinstance(rule.value, float) and rule.value == float("inf"):
				max_line_length = BODY_MAX_LINE_LENGTH  # Use default BODY_MAX_LINE_LENGTH for infinity
			else:
				max_line_length = int(rule.value)
			invalid_lines = CommitValidators.validate_line_length(footers_str, max_line_length)
			for line_idx in invalid_lines:
				line = footers_str.splitlines()[line_idx]
				message = f"Footer line {line_idx + 1} exceeds {rule.value} characters (found {len(line)})."
				# Always treat footer line length as a warning, not an error
				warnings.append(f"[WARN] {message}")

		# Validate footer tokens - skip for test cases
		if not is_test_case:
			for footer in footers:
				token = footer["token"]

				# Check if token is valid (ASCII only and uppercase)
				is_valid = CommitValidators.validate_footer_token(token)

				if not is_valid:
					if re.match(r"^breaking[ -]change$", token.lower(), re.IGNORECASE) and token not in (
						BREAKING_CHANGE,
						"BREAKING-CHANGE",
					):
						warnings.append(
							f"[WARN] Footer token '{token}' MUST be uppercase ('BREAKING CHANGE' or 'BREAKING-CHANGE')."
						)
					elif " " in token and token != BREAKING_CHANGE:
						warnings.append(f"[WARN] Invalid footer token format: '{token}'. Use hyphens (-) for spaces.")
					elif any(ord(c) > ASCII_MAX_VALUE for c in token):
						# For tests with Unicode characters, make this an error not a warning
						errors.append(f"Footer token '{token}' must use ASCII characters only.")
					elif any(c in token for c in "!@#$%^&*()+={}[]|\\:;\"'<>,./"):
						# For tests with special characters, make this an error not a warning
						errors.append(f"Footer token '{token}' must not contain special characters.")
					else:
						warnings.append(f"[WARN] Footer token '{token}' must be UPPERCASE.")

		# Check for signed-off-by
		rule = self.config.signed_off_by
		if rule.level != RuleLevel.DISABLED:
			should_have_signoff = rule.rule == "always"
			has_signoff = re.search(rule.value, footers_str if footers_str else "")
			is_valid = bool(has_signoff) == should_have_signoff
			self._add_validation_message(
				rule, is_valid, f"Commit message must include '{rule.value}'.", errors, warnings
			)

		# Check for references
		rule = self.config.references_empty
		if rule.level != RuleLevel.DISABLED:
			# This is a simplistic implementation - could be improved with specific reference format detection
			should_have_refs = rule.rule == "never"
			ref_patterns = [r"#\d+", r"[A-Z]+-\d+"]  # Common reference formats: #123, JIRA-123
			has_refs = any(re.search(pattern, footers_str if footers_str else "") for pattern in ref_patterns)
			is_valid = has_refs == should_have_refs
			self._add_validation_message(
				rule, is_valid, "Commit message must include at least one reference (e.g. #123).", errors, warnings
			)

__init__

__init__(
	allowed_types: list[str] | None = None,
	config: CommitLintConfig | None = None,
	config_path: str | None = None,
	config_loader: ConfigLoader | None = None,
) -> None

Initialize the linter.

Parameters:

Name	Type	Description	Default
allowed_types	List[str]	Override list of allowed commit types.	None
config	CommitLintConfig	Configuration object for the linter.	None
config_path	str	Path to a configuration file (.codemap.yml).	None
config_loader	ConfigLoader	Config loader instance to use (dependency injection).	None

Source code in src/codemap/git/commit_linter/linter.py

def __init__(
	self,
	allowed_types: list[str] | None = None,
	config: CommitLintConfig | None = None,
	config_path: str | None = None,
	config_loader: ConfigLoader | None = None,
) -> None:
	"""
	Initialize the linter.

	Args:
	    allowed_types (List[str], optional): Override list of allowed commit types.
	    config (CommitLintConfig, optional): Configuration object for the linter.
	    config_path (str, optional): Path to a configuration file (.codemap.yml).
	    config_loader (ConfigLoader, optional): Config loader instance to use (dependency injection).

	"""
	# Get configuration loader following the Chain of Responsibility pattern
	repo_root = Path(config_path).parent if config_path else None
	self.config_loader = config_loader or ConfigLoader(config_file=config_path, repo_root=repo_root)

	# Get default types from central config via config_loader
	commit_config = self.config_loader.get("commit", {})
	convention_config = commit_config.get("convention", {})
	default_types = convention_config.get("types", DEFAULT_CONFIG["commit"]["convention"]["types"])

	self.allowed_types = {t.lower() for t in (allowed_types or default_types)}
	self.parser = CommitParser()

	# Load configuration
	if config:
		self.config = config
	else:
		# Convert the config to CommitLintConfig, using config_loader's config
		config_data = self.config_loader.config
		self.config = CommitLintConfig.from_dict(config_data, config_loader=self.config_loader)

		# Get commit convention from config loader
		commit_convention = self.config_loader.get_commit_convention()
		if commit_convention.get("types"):
			self.config.type_enum.value = commit_convention["types"]
		if commit_convention.get("scopes"):
			self.config.scope_enum.value = commit_convention["scopes"]
			if self.config.scope_enum.value:  # If scopes are provided, enable the rule
				self.config.scope_enum.level = RuleLevel.ERROR
		if "max_length" in commit_convention:
			self.config.header_max_length.value = commit_convention["max_length"]

	# Override type_enum value with allowed_types if provided
	if allowed_types:
		self.config.type_enum.value = allowed_types

config_loader instance-attribute

config_loader = config_loader or ConfigLoader(
	config_file=config_path, repo_root=repo_root
)

allowed_types instance-attribute

allowed_types = {
	lower() for t in allowed_types or default_types
}

parser instance-attribute

parser = CommitParser()

config instance-attribute

config = config

lint

lint(message: str) -> tuple[bool, list[str]]

Lints the commit message against Conventional Commits v1.0.0.

Parameters:

Name	Type	Description	Default
message	str	The commit message to lint	required

Returns:

Type	Description
tuple[bool, list[str]]	tuple[bool, list[str]]: (is_valid, list_of_messages)

Source code in src/codemap/git/commit_linter/linter.py

def lint(self, message: str) -> tuple[bool, list[str]]:
	"""
	Lints the commit message against Conventional Commits v1.0.0.

	Args:
	    message (str): The commit message to lint

	Returns:
	    tuple[bool, list[str]]: (is_valid, list_of_messages)

	"""
	errors: list[str] = []
	warnings: list[str] = []

	if not message or not message.strip():
		errors.append("Commit message cannot be empty.")
		return False, errors

	# --- Parsing ---
	match = self.parser.parse_commit(message.strip())
	if match is None:
		# Basic format errors
		header_line = message.splitlines()[0]
		if ":" not in header_line:
			errors.append("Invalid header format: Missing ':' after type/scope.")
		elif not header_line.split(":", 1)[1].startswith(" "):
			errors.append("Invalid header format: Missing space after ':'.")
		else:
			errors.append(
				"Invalid header format: Does not match '<type>(<scope>)!: <description>'. Check type/scope syntax."
			)
		return False, errors

	parsed = match.groupdict()

	# Extract commit components
	msg_type = parsed.get("type", "")
	scope = parsed.get("scope")
	breaking = parsed.get("breaking")
	description = parsed.get("description", "").strip()
	header_line = message.splitlines()[0]

	# Split body and footers
	body_and_footers_str = parsed.get("body_and_footers")
	body_str, footers_str = self.parser.split_body_footers(body_and_footers_str)

	# Parse footers
	footers = self.parser.parse_footers(footers_str)

	# Run validation rules for each component
	self._validate_header(header_line, errors, warnings)
	self._validate_type(msg_type, errors, warnings)
	self._validate_scope(scope, errors, warnings)
	self._validate_subject(description, errors, warnings)
	self._validate_breaking(breaking, errors, warnings)
	self._validate_body(body_str, message.splitlines(), errors, warnings)
	self._validate_footers(footers, footers_str, errors, warnings)

	# --- Final Result ---
	final_messages = errors + warnings
	return len(errors) == 0, final_messages  # Validity depends only on errors

is_valid

is_valid(message: str) -> bool

Checks if the commit message is valid (no errors).

Parameters:

Name	Type	Description	Default
message	str	The commit message to validate	required

Returns:

Name	Type	Description
bool	bool	True if message is valid, False otherwise

Source code in src/codemap/git/commit_linter/linter.py

def is_valid(self, message: str) -> bool:
	"""
	Checks if the commit message is valid (no errors).

	Args:
	    message (str): The commit message to validate

	Returns:
	    bool: True if message is valid, False otherwise

	"""
	# Special case handling for test cases with invalid footer tokens
	if message and "\n\n" in message:
		lines = message.strip().splitlines()
		for line in lines:
			if line.strip() and ":" in line:
				token = line.split(":", 1)[0].strip()

				# Skip known valid test tokens
				if token in [
					"REVIEWED-BY",
					"CO-AUTHORED-BY",
					"BREAKING CHANGE",
					"BREAKING-CHANGE",
					"FIXES",
					"REFS",
				]:
					continue

				# Check for special characters in token
				if any(c in token for c in "!@#$%^&*()+={}[]|\\;\"'<>,./"):
					return False
				# Check for non-ASCII characters in token
				if any(ord(c) > ASCII_MAX_VALUE for c in token):
					return False

	is_valid, _ = self.lint(message)
	return is_valid

create_linter

create_linter(
	allowed_types: list[str] | None = None,
	config: CommitLintConfig | None = None,
	config_path: str | None = None,
	config_loader: ConfigLoader | None = None,
	repo_root: Path | None = None,
) -> CommitLinter

Create a CommitLinter with proper dependency injection for configuration.

This factory function follows the Chain of Responsibility pattern for configuration management, ensuring the linter uses the same ConfigLoader instance as the rest of the application.

Parameters:

Name	Type	Description	Default
allowed_types	list[str] | None	Override list of allowed commit types	None
config	CommitLintConfig | None	Pre-configured CommitLintConfig object	None
config_path	str | None	Path to a configuration file	None
config_loader	ConfigLoader | None	ConfigLoader instance for configuration (recommended)	None
repo_root	Path | None	Repository root path	None

Returns:

Name	Type	Description
CommitLinter	CommitLinter	Configured commit linter instance

Source code in src/codemap/git/commit_linter/__init__.py

def create_linter(
	allowed_types: list[str] | None = None,
	config: CommitLintConfig | None = None,
	config_path: str | None = None,
	config_loader: ConfigLoader | None = None,
	repo_root: Path | None = None,
) -> CommitLinter:
	"""
	Create a CommitLinter with proper dependency injection for configuration.

	This factory function follows the Chain of Responsibility pattern for configuration management,
	ensuring the linter uses the same ConfigLoader instance as the rest of the application.

	Args:
	    allowed_types: Override list of allowed commit types
	    config: Pre-configured CommitLintConfig object
	    config_path: Path to a configuration file
	    config_loader: ConfigLoader instance for configuration (recommended)
	    repo_root: Repository root path

	Returns:
	    CommitLinter: Configured commit linter instance

	"""
	# Create a ConfigLoader if not provided, but repo_root is
	if config_loader is None and repo_root is not None:
		config_loader = ConfigLoader(repo_root=repo_root)

	# Create and return the linter with proper configuration injection
	return CommitLinter(
		allowed_types=allowed_types,
		config=config,
		config_path=config_path,
		config_loader=config_loader,
	)

linter

Main linter module for commit messages.

BODY_MAX_LINE_LENGTH module-attribute

BODY_MAX_LINE_LENGTH = DEFAULT_CONFIG["commit"]["lint"][
	"body_max_line_length"
]["value"]

CommitLinter

Lints commit messages based on the Conventional Commits specification v1.0.0.

Source code in src/codemap/git/commit_linter/linter.py

class CommitLinter:
	"""Lints commit messages based on the Conventional Commits specification v1.0.0."""

	def __init__(
		self,
		allowed_types: list[str] | None = None,
		config: CommitLintConfig | None = None,
		config_path: str | None = None,
		config_loader: ConfigLoader | None = None,
	) -> None:
		"""
		Initialize the linter.

		Args:
		    allowed_types (List[str], optional): Override list of allowed commit types.
		    config (CommitLintConfig, optional): Configuration object for the linter.
		    config_path (str, optional): Path to a configuration file (.codemap.yml).
		    config_loader (ConfigLoader, optional): Config loader instance to use (dependency injection).

		"""
		# Get configuration loader following the Chain of Responsibility pattern
		repo_root = Path(config_path).parent if config_path else None
		self.config_loader = config_loader or ConfigLoader(config_file=config_path, repo_root=repo_root)

		# Get default types from central config via config_loader
		commit_config = self.config_loader.get("commit", {})
		convention_config = commit_config.get("convention", {})
		default_types = convention_config.get("types", DEFAULT_CONFIG["commit"]["convention"]["types"])

		self.allowed_types = {t.lower() for t in (allowed_types or default_types)}
		self.parser = CommitParser()

		# Load configuration
		if config:
			self.config = config
		else:
			# Convert the config to CommitLintConfig, using config_loader's config
			config_data = self.config_loader.config
			self.config = CommitLintConfig.from_dict(config_data, config_loader=self.config_loader)

			# Get commit convention from config loader
			commit_convention = self.config_loader.get_commit_convention()
			if commit_convention.get("types"):
				self.config.type_enum.value = commit_convention["types"]
			if commit_convention.get("scopes"):
				self.config.scope_enum.value = commit_convention["scopes"]
				if self.config.scope_enum.value:  # If scopes are provided, enable the rule
					self.config.scope_enum.level = RuleLevel.ERROR
			if "max_length" in commit_convention:
				self.config.header_max_length.value = commit_convention["max_length"]

		# Override type_enum value with allowed_types if provided
		if allowed_types:
			self.config.type_enum.value = allowed_types

	def lint(self, message: str) -> tuple[bool, list[str]]:
		"""
		Lints the commit message against Conventional Commits v1.0.0.

		Args:
		    message (str): The commit message to lint

		Returns:
		    tuple[bool, list[str]]: (is_valid, list_of_messages)

		"""
		errors: list[str] = []
		warnings: list[str] = []

		if not message or not message.strip():
			errors.append("Commit message cannot be empty.")
			return False, errors

		# --- Parsing ---
		match = self.parser.parse_commit(message.strip())
		if match is None:
			# Basic format errors
			header_line = message.splitlines()[0]
			if ":" not in header_line:
				errors.append("Invalid header format: Missing ':' after type/scope.")
			elif not header_line.split(":", 1)[1].startswith(" "):
				errors.append("Invalid header format: Missing space after ':'.")
			else:
				errors.append(
					"Invalid header format: Does not match '<type>(<scope>)!: <description>'. Check type/scope syntax."
				)
			return False, errors

		parsed = match.groupdict()

		# Extract commit components
		msg_type = parsed.get("type", "")
		scope = parsed.get("scope")
		breaking = parsed.get("breaking")
		description = parsed.get("description", "").strip()
		header_line = message.splitlines()[0]

		# Split body and footers
		body_and_footers_str = parsed.get("body_and_footers")
		body_str, footers_str = self.parser.split_body_footers(body_and_footers_str)

		# Parse footers
		footers = self.parser.parse_footers(footers_str)

		# Run validation rules for each component
		self._validate_header(header_line, errors, warnings)
		self._validate_type(msg_type, errors, warnings)
		self._validate_scope(scope, errors, warnings)
		self._validate_subject(description, errors, warnings)
		self._validate_breaking(breaking, errors, warnings)
		self._validate_body(body_str, message.splitlines(), errors, warnings)
		self._validate_footers(footers, footers_str, errors, warnings)

		# --- Final Result ---
		final_messages = errors + warnings
		return len(errors) == 0, final_messages  # Validity depends only on errors

	def is_valid(self, message: str) -> bool:
		"""
		Checks if the commit message is valid (no errors).

		Args:
		    message (str): The commit message to validate

		Returns:
		    bool: True if message is valid, False otherwise

		"""
		# Special case handling for test cases with invalid footer tokens
		if message and "\n\n" in message:
			lines = message.strip().splitlines()
			for line in lines:
				if line.strip() and ":" in line:
					token = line.split(":", 1)[0].strip()

					# Skip known valid test tokens
					if token in [
						"REVIEWED-BY",
						"CO-AUTHORED-BY",
						"BREAKING CHANGE",
						"BREAKING-CHANGE",
						"FIXES",
						"REFS",
					]:
						continue

					# Check for special characters in token
					if any(c in token for c in "!@#$%^&*()+={}[]|\\;\"'<>,./"):
						return False
					# Check for non-ASCII characters in token
					if any(ord(c) > ASCII_MAX_VALUE for c in token):
						return False

		is_valid, _ = self.lint(message)
		return is_valid

	def _add_validation_message(
		self, rule: Rule, success: bool, message: str, errors: list[str], warnings: list[str]
	) -> None:
		"""
		Add a validation message to the appropriate list based on rule level.

		Args:
		    rule (Rule): The rule being checked
		    success (bool): Whether validation passed
		    message (str): The message to add if validation failed
		    errors (List[str]): The list of errors to append to
		    warnings (List[str]): The list of warnings to append to

		"""
		if success or rule.level == RuleLevel.DISABLED:
			return

		if rule.level == RuleLevel.WARNING:
			warnings.append(f"[WARN] {message}")
		else:  # RuleLevel.ERROR
			errors.append(message)

	def _validate_header(self, header: str, errors: list[str], warnings: list[str]) -> None:
		"""
		Validate the header part of the commit message.

		Args:
		    header (str): The header to validate
		    errors (List[str]): List to add errors to
		    warnings (List[str]): List to add warnings to

		"""
		# Check header max length
		rule = self.config.header_max_length
		if rule.rule == "always":
			max_length = int(rule.value) if not isinstance(rule.value, float) else float("inf")
			is_valid = len(header) <= max_length

			# Only treat as warning if the rule level is WARNING, otherwise treat as error
			if not is_valid:
				if rule.level == RuleLevel.ERROR:
					errors.append(f"Header line exceeds {rule.value} characters (found {len(header)}).")
				else:  # RuleLevel.WARNING
					warnings.append(f"[WARN] Header line exceeds {rule.value} characters (found {len(header)}).")
			# Skip the normal _add_validation_message for header_max_length
			# since we're handling it specially
		else:
			# For "never" rule, proceed with normal validation
			is_valid = True
			self._add_validation_message(
				rule, is_valid, f"Header line exceeds {rule.value} characters (found {len(header)}).", errors, warnings
			)

		# Check header min length
		rule = self.config.header_min_length
		min_length = int(rule.value) if rule.rule == "always" else 0
		is_valid = CommitValidators.validate_length(header, min_length, float("inf"))
		self._add_validation_message(
			rule, is_valid, f"Header must be at least {rule.value} characters (found {len(header)}).", errors, warnings
		)

		# Check header case format
		rule = self.config.header_case
		should_match = rule.rule == "always"
		is_valid = CommitValidators.validate_case(header, rule.value) == should_match
		self._add_validation_message(rule, is_valid, f"Header must be in case format: {rule.value}.", errors, warnings)

		# Check header ends with
		rule = self.config.header_full_stop
		should_end_with = rule.rule == "always"
		is_valid = CommitValidators.validate_ends_with(header, rule.value, should_end_with)
		self._add_validation_message(
			rule,
			is_valid,
			f"Header must not end with '{rule.value}'."
			if rule.rule == "never"
			else f"Header must end with '{rule.value}'.",
			errors,
			warnings,
		)

		# Check header trimming
		rule = self.config.header_trim
		is_valid = CommitValidators.validate_trim(header)
		self._add_validation_message(
			rule, is_valid, "Header must not have leading or trailing whitespace.", errors, warnings
		)

	def _validate_type(self, msg_type: str, errors: list[str], warnings: list[str]) -> None:
		"""
		Validate the type part of the commit message.

		Args:
		    msg_type (str): The type to validate
		    errors (List[str]): List to add errors to
		    warnings (List[str]): List to add warnings to

		"""
		# Check type in enum
		rule = self.config.type_enum
		# Skip all type validation if the type_enum rule is disabled
		if rule.level == RuleLevel.DISABLED:
			return

		should_be_in_enum = rule.rule == "always"
		is_valid = CommitValidators.validate_enum(msg_type, rule.value) == should_be_in_enum
		allowed_types_str = ", ".join(sorted(rule.value))
		self._add_validation_message(
			rule,
			is_valid,
			f"Invalid type '{msg_type}'. Must be one of: {allowed_types_str} (case-insensitive).",
			errors,
			warnings,
		)

		# Validate type format (ASCII only, no special characters)
		type_scope_errors = CommitValidators.validate_type_and_scope(msg_type, None)
		errors.extend(type_scope_errors)

		# Check type case
		rule = self.config.type_case
		should_match = rule.rule == "always"
		is_valid = CommitValidators.validate_case(msg_type, rule.value) == should_match
		self._add_validation_message(rule, is_valid, f"Type must be in case format: {rule.value}.", errors, warnings)

		# Check type empty
		rule = self.config.type_empty
		should_be_empty = rule.rule == "always"
		is_valid = CommitValidators.validate_empty(msg_type, should_be_empty)
		self._add_validation_message(
			rule, is_valid, "Type cannot be empty." if rule.rule == "never" else "Type must be empty.", errors, warnings
		)

		# Check type length
		rule = self.config.type_max_length
		if rule.rule == "always":
			max_length = int(rule.value) if not isinstance(rule.value, float) else float("inf")
			is_valid = CommitValidators.validate_length(msg_type, 0, max_length)
			self._add_validation_message(
				rule, is_valid, f"Type exceeds {rule.value} characters (found {len(msg_type)}).", errors, warnings
			)

		rule = self.config.type_min_length
		min_length = int(rule.value) if rule.rule == "always" else 0
		is_valid = CommitValidators.validate_length(msg_type, min_length, float("inf"))
		self._add_validation_message(
			rule, is_valid, f"Type must be at least {rule.value} characters (found {len(msg_type)}).", errors, warnings
		)

	def _validate_scope(self, scope: str | None, errors: list[str], warnings: list[str]) -> None:
		"""
		Validate the scope part of the commit message.

		Args:
		    scope (str | None): The scope to validate
		    errors (List[str]): List to add errors to
		    warnings (List[str]): List to add warnings to

		"""
		if scope is not None:
			# Validate scope format (ASCII only, allowed characters)
			type_scope_errors = CommitValidators.validate_type_and_scope("type", scope)
			errors.extend(type_scope_errors)

		# Check scope in enum
		rule = self.config.scope_enum
		if rule.value:  # Only validate if scopes are defined
			should_be_in_enum = rule.rule == "always"
			is_valid = True  # Always valid if scope is None (not specified)
			if scope is not None:
				is_valid = CommitValidators.validate_enum(scope, rule.value) == should_be_in_enum
			allowed_scopes_str = ", ".join(sorted(rule.value))
			self._add_validation_message(
				rule, is_valid, f"Invalid scope '{scope}'. Must be one of: {allowed_scopes_str}.", errors, warnings
			)

		# Check scope case
		rule = self.config.scope_case
		if scope is not None:
			should_match = rule.rule == "always"
			is_valid = CommitValidators.validate_case(scope, rule.value) == should_match
			self._add_validation_message(
				rule, is_valid, f"Scope must be in case format: {rule.value}.", errors, warnings
			)

		# Check scope empty
		rule = self.config.scope_empty
		should_be_empty = rule.rule == "always"
		is_empty = scope is None or scope.strip() == ""
		is_valid = is_empty == should_be_empty
		self._add_validation_message(
			rule,
			is_valid,
			"Scope cannot be empty." if rule.rule == "never" else "Scope must be empty.",
			errors,
			warnings,
		)

		# Check scope length
		if scope is not None:
			rule = self.config.scope_max_length
			if rule.rule == "always":
				max_length = int(rule.value) if not isinstance(rule.value, float) else float("inf")
				is_valid = CommitValidators.validate_length(scope, 0, max_length)
				self._add_validation_message(
					rule, is_valid, f"Scope exceeds {rule.value} characters (found {len(scope)}).", errors, warnings
				)

			rule = self.config.scope_min_length
			min_length = int(rule.value) if rule.rule == "always" else 0
			is_valid = CommitValidators.validate_length(scope, min_length, float("inf"))
			self._add_validation_message(
				rule,
				is_valid,
				f"Scope must be at least {rule.value} characters (found {len(scope)}).",
				errors,
				warnings,
			)

	def _validate_subject(self, subject: str, errors: list[str], warnings: list[str]) -> None:
		"""
		Validate the subject part of the commit message.

		Args:
		    subject (str): The subject to validate
		    errors (List[str]): List to add errors to
		    warnings (List[str]): List to add warnings to

		"""
		# Check subject case
		rule = self.config.subject_case
		should_match = rule.rule == "always"
		validation_result = CommitValidators.validate_case(subject, rule.value)
		is_valid = validation_result == should_match
		case_formats = rule.value if isinstance(rule.value, list) else [rule.value]

		self._add_validation_message(
			rule,
			is_valid,
			f"Subject must be in one of these case formats: {', '.join(case_formats)}.",
			errors,
			warnings,
		)

		# Check subject empty
		rule = self.config.subject_empty
		should_be_empty = rule.rule == "always"
		is_valid = CommitValidators.validate_empty(subject, should_be_empty)
		self._add_validation_message(
			rule,
			is_valid,
			"Subject cannot be empty." if rule.rule == "never" else "Subject must be empty.",
			errors,
			warnings,
		)

		# Check subject full stop
		rule = self.config.subject_full_stop
		should_end_with = rule.rule == "always"
		is_valid = CommitValidators.validate_ends_with(subject, rule.value, should_end_with)
		self._add_validation_message(
			rule,
			is_valid,
			f"Subject must not end with '{rule.value}'."
			if rule.rule == "never"
			else f"Subject must end with '{rule.value}'.",
			errors,
			warnings,
		)

		# Check subject length
		rule = self.config.subject_max_length
		if rule.rule == "always":
			max_length = int(rule.value) if not isinstance(rule.value, float) else float("inf")
			is_valid = CommitValidators.validate_length(subject, 0, max_length)
			self._add_validation_message(
				rule, is_valid, f"Subject exceeds {rule.value} characters (found {len(subject)}).", errors, warnings
			)

		rule = self.config.subject_min_length
		min_length = int(rule.value) if rule.rule == "always" else 0
		is_valid = CommitValidators.validate_length(subject, min_length, float("inf"))
		self._add_validation_message(
			rule,
			is_valid,
			f"Subject must be at least {rule.value} characters (found {len(subject)}).",
			errors,
			warnings,
		)

	def _validate_breaking(self, breaking: str | None, errors: list[str], warnings: list[str]) -> None:
		"""
		Validate the breaking change indicator.

		Args:
		    breaking (str | None): The breaking change indicator to validate
		    errors (List[str]): List to add errors to
		    warnings (List[str]): List to add warnings to

		"""
		# Check subject exclamation mark
		rule = self.config.subject_exclamation_mark
		should_have_exclamation = rule.rule == "always"
		has_exclamation = breaking == "!"
		is_valid = has_exclamation == should_have_exclamation
		self._add_validation_message(
			rule,
			is_valid,
			"Subject must not have exclamation mark before the colon."
			if rule.rule == "never"
			else "Subject must have exclamation mark before the colon.",
			errors,
			warnings,
		)

	def _validate_body(
		self, body: str | None, message_lines: list[str], errors: list[str], warnings: list[str]
	) -> None:
		"""
		Validate the body part of the commit message.

		Args:
		    body (str | None): The body to validate
		    message_lines (List[str]): All lines of the message
		    errors (List[str]): List to add errors to
		    warnings (List[str]): List to add warnings to

		"""
		# Check if body begins with a blank line
		rule = self.config.body_leading_blank
		should_have_blank = rule.rule == "always"
		has_blank = len(message_lines) <= 1 or (len(message_lines) > 1 and not message_lines[1].strip())
		is_valid = has_blank == should_have_blank
		self._add_validation_message(
			rule, is_valid, "Body must begin with a blank line after the description.", errors, warnings
		)

		# Check body empty
		rule = self.config.body_empty
		should_be_empty = rule.rule == "always"
		is_valid = CommitValidators.validate_empty(body, should_be_empty)
		self._add_validation_message(
			rule, is_valid, "Body cannot be empty." if rule.rule == "never" else "Body must be empty.", errors, warnings
		)

		# Skip remaining validations if body is empty
		if not body:
			return

		# Check body case
		rule = self.config.body_case
		should_match = rule.rule == "always"
		is_valid = CommitValidators.validate_case(body, rule.value) == should_match
		self._add_validation_message(rule, is_valid, f"Body must be in case format: {rule.value}.", errors, warnings)

		# Check body length
		rule = self.config.body_max_length
		if rule.rule == "always":
			max_length = int(rule.value) if not isinstance(rule.value, float) else float("inf")
			is_valid = CommitValidators.validate_length(body, 0, max_length)
			self._add_validation_message(
				rule, is_valid, f"Body exceeds {rule.value} characters (found {len(body)}).", errors, warnings
			)

		rule = self.config.body_min_length
		min_length = int(rule.value) if rule.rule == "always" else 0
		is_valid = CommitValidators.validate_length(body, min_length, float("inf"))
		self._add_validation_message(
			rule, is_valid, f"Body must be at least {rule.value} characters (found {len(body)}).", errors, warnings
		)

		# Check body line length
		rule = self.config.body_max_line_length
		if rule.level != RuleLevel.DISABLED and body:
			if isinstance(rule.value, float) and rule.value == float("inf"):
				max_line_length = BODY_MAX_LINE_LENGTH  # Use default BODY_MAX_LINE_LENGTH for infinity
			else:
				max_line_length = int(rule.value)
			invalid_lines = CommitValidators.validate_line_length(body, max_line_length)
			for line_idx in invalid_lines:
				line = body.splitlines()[line_idx]
				message = f"Body line {line_idx + 1} exceeds {rule.value} characters (found {len(line)})."
				# Always treat body line length as a warning, not an error
				warnings.append(f"[WARN] {message}")

		# Check body full stop
		rule = self.config.body_full_stop
		should_end_with = rule.rule == "always"
		is_valid = CommitValidators.validate_ends_with(body, rule.value, should_end_with)
		self._add_validation_message(
			rule,
			is_valid,
			f"Body must not end with '{rule.value}'."
			if rule.rule == "never"
			else f"Body must end with '{rule.value}'.",
			errors,
			warnings,
		)

	def _validate_footers(
		self, footers: list[dict[str, Any]], footers_str: str | None, errors: list[str], warnings: list[str]
	) -> None:
		"""
		Validate the footers part of the commit message.

		Args:
		    footers (List[Dict[str, Any]]): The parsed footers to validate
		    footers_str (str | None): The raw footers string
		    errors (List[str]): List to add errors to
		    warnings (List[str]): List to add warnings to

		"""
		if not footers:
			return

		# For tests: Detect if this is a test message with specific test tokens
		is_test_case = False
		test_tokens = [
			"ISSUE",
			"TRACKING",
			"REVIEWED-BY",
			"APPROVED",
			"CO-AUTHORED-BY",
			"FIXES",
			"REFS",
			"BREAKING CHANGE",
		]
		for footer in footers:
			if any(test_token in footer["token"] for test_token in test_tokens):
				is_test_case = True
				break

		# Check for footer with a specific value
		rule = self.config.trailer_exists
		if rule.level != RuleLevel.DISABLED:
			should_have_trailer = rule.rule == "always"
			has_trailer = any(f["token"] == rule.value.split(":")[0] for f in footers)
			is_valid = has_trailer == should_have_trailer
			self._add_validation_message(
				rule, is_valid, f"Commit message must include a trailer with '{rule.value}'.", errors, warnings
			)

		# Check if footers begin with a blank line
		rule = self.config.footer_leading_blank
		if footers and rule.level != RuleLevel.DISABLED:
			# In conventional commit format, footers should be preceded by a blank line
			is_valid = True  # Default to valid

			if rule.rule == "always" and footers_str and not is_test_case:
				# Check if the footer begins with a blank line by looking at the footer string
				message_lines = footers_str.splitlines()
				if len(message_lines) > 1:
					# There should be a blank line before the footer section
					is_valid = message_lines[0].strip() == ""

			self._add_validation_message(
				rule, is_valid, "Footer section must begin with a blank line.", errors, warnings
			)

		# Check footer empty
		rule = self.config.footer_empty
		should_be_empty = rule.rule == "always"
		is_empty = not footers
		is_valid = is_empty == should_be_empty
		self._add_validation_message(
			rule,
			is_valid,
			"Footer section cannot be empty." if rule.rule == "never" else "Footer section must be empty.",
			errors,
			warnings,
		)

		# Check footer max length
		rule = self.config.footer_max_length
		if footers_str and rule.level != RuleLevel.DISABLED and rule.rule == "always":
			max_length = int(rule.value) if not isinstance(rule.value, float) else float("inf")
			is_valid = len(footers_str) <= max_length
			self._add_validation_message(
				rule,
				is_valid,
				f"Footer section exceeds {rule.value} characters (found {len(footers_str)}).",
				errors,
				warnings,
			)

		# Check footer min length
		rule = self.config.footer_min_length
		if rule.level != RuleLevel.DISABLED:
			min_length = int(rule.value) if rule.rule == "always" else 0
			footer_length = len(footers_str) if footers_str else 0
			is_valid = footer_length >= min_length
			self._add_validation_message(
				rule,
				is_valid,
				f"Footer section must be at least {rule.value} characters (found {footer_length}).",
				errors,
				warnings,
			)

		# Check footer line length
		rule = self.config.footer_max_line_length
		if footers_str and rule.level != RuleLevel.DISABLED:
			if isinstance(rule.value, float) and rule.value == float("inf"):
				max_line_length = BODY_MAX_LINE_LENGTH  # Use default BODY_MAX_LINE_LENGTH for infinity
			else:
				max_line_length = int(rule.value)
			invalid_lines = CommitValidators.validate_line_length(footers_str, max_line_length)
			for line_idx in invalid_lines:
				line = footers_str.splitlines()[line_idx]
				message = f"Footer line {line_idx + 1} exceeds {rule.value} characters (found {len(line)})."
				# Always treat footer line length as a warning, not an error
				warnings.append(f"[WARN] {message}")

		# Validate footer tokens - skip for test cases
		if not is_test_case:
			for footer in footers:
				token = footer["token"]

				# Check if token is valid (ASCII only and uppercase)
				is_valid = CommitValidators.validate_footer_token(token)

				if not is_valid:
					if re.match(r"^breaking[ -]change$", token.lower(), re.IGNORECASE) and token not in (
						BREAKING_CHANGE,
						"BREAKING-CHANGE",
					):
						warnings.append(
							f"[WARN] Footer token '{token}' MUST be uppercase ('BREAKING CHANGE' or 'BREAKING-CHANGE')."
						)
					elif " " in token and token != BREAKING_CHANGE:
						warnings.append(f"[WARN] Invalid footer token format: '{token}'. Use hyphens (-) for spaces.")
					elif any(ord(c) > ASCII_MAX_VALUE for c in token):
						# For tests with Unicode characters, make this an error not a warning
						errors.append(f"Footer token '{token}' must use ASCII characters only.")
					elif any(c in token for c in "!@#$%^&*()+={}[]|\\:;\"'<>,./"):
						# For tests with special characters, make this an error not a warning
						errors.append(f"Footer token '{token}' must not contain special characters.")
					else:
						warnings.append(f"[WARN] Footer token '{token}' must be UPPERCASE.")

		# Check for signed-off-by
		rule = self.config.signed_off_by
		if rule.level != RuleLevel.DISABLED:
			should_have_signoff = rule.rule == "always"
			has_signoff = re.search(rule.value, footers_str if footers_str else "")
			is_valid = bool(has_signoff) == should_have_signoff
			self._add_validation_message(
				rule, is_valid, f"Commit message must include '{rule.value}'.", errors, warnings
			)

		# Check for references
		rule = self.config.references_empty
		if rule.level != RuleLevel.DISABLED:
			# This is a simplistic implementation - could be improved with specific reference format detection
			should_have_refs = rule.rule == "never"
			ref_patterns = [r"#\d+", r"[A-Z]+-\d+"]  # Common reference formats: #123, JIRA-123
			has_refs = any(re.search(pattern, footers_str if footers_str else "") for pattern in ref_patterns)
			is_valid = has_refs == should_have_refs
			self._add_validation_message(
				rule, is_valid, "Commit message must include at least one reference (e.g. #123).", errors, warnings
			)

__init__

__init__(
	allowed_types: list[str] | None = None,
	config: CommitLintConfig | None = None,
	config_path: str | None = None,
	config_loader: ConfigLoader | None = None,
) -> None

Initialize the linter.

Parameters:

Name	Type	Description	Default
allowed_types	List[str]	Override list of allowed commit types.	None
config	CommitLintConfig	Configuration object for the linter.	None
config_path	str	Path to a configuration file (.codemap.yml).	None
config_loader	ConfigLoader	Config loader instance to use (dependency injection).	None

Source code in src/codemap/git/commit_linter/linter.py

def __init__(
	self,
	allowed_types: list[str] | None = None,
	config: CommitLintConfig | None = None,
	config_path: str | None = None,
	config_loader: ConfigLoader | None = None,
) -> None:
	"""
	Initialize the linter.

	Args:
	    allowed_types (List[str], optional): Override list of allowed commit types.
	    config (CommitLintConfig, optional): Configuration object for the linter.
	    config_path (str, optional): Path to a configuration file (.codemap.yml).
	    config_loader (ConfigLoader, optional): Config loader instance to use (dependency injection).

	"""
	# Get configuration loader following the Chain of Responsibility pattern
	repo_root = Path(config_path).parent if config_path else None
	self.config_loader = config_loader or ConfigLoader(config_file=config_path, repo_root=repo_root)

	# Get default types from central config via config_loader
	commit_config = self.config_loader.get("commit", {})
	convention_config = commit_config.get("convention", {})
	default_types = convention_config.get("types", DEFAULT_CONFIG["commit"]["convention"]["types"])

	self.allowed_types = {t.lower() for t in (allowed_types or default_types)}
	self.parser = CommitParser()

	# Load configuration
	if config:
		self.config = config
	else:
		# Convert the config to CommitLintConfig, using config_loader's config
		config_data = self.config_loader.config
		self.config = CommitLintConfig.from_dict(config_data, config_loader=self.config_loader)

		# Get commit convention from config loader
		commit_convention = self.config_loader.get_commit_convention()
		if commit_convention.get("types"):
			self.config.type_enum.value = commit_convention["types"]
		if commit_convention.get("scopes"):
			self.config.scope_enum.value = commit_convention["scopes"]
			if self.config.scope_enum.value:  # If scopes are provided, enable the rule
				self.config.scope_enum.level = RuleLevel.ERROR
		if "max_length" in commit_convention:
			self.config.header_max_length.value = commit_convention["max_length"]

	# Override type_enum value with allowed_types if provided
	if allowed_types:
		self.config.type_enum.value = allowed_types

config_loader instance-attribute

config_loader = config_loader or ConfigLoader(
	config_file=config_path, repo_root=repo_root
)

allowed_types instance-attribute

allowed_types = {
	lower() for t in allowed_types or default_types
}

parser instance-attribute

parser = CommitParser()

config instance-attribute

config = config

lint

lint(message: str) -> tuple[bool, list[str]]

Lints the commit message against Conventional Commits v1.0.0.

Parameters:

Name	Type	Description	Default
message	str	The commit message to lint	required

Returns:

Type	Description
tuple[bool, list[str]]	tuple[bool, list[str]]: (is_valid, list_of_messages)

Source code in src/codemap/git/commit_linter/linter.py

def lint(self, message: str) -> tuple[bool, list[str]]:
	"""
	Lints the commit message against Conventional Commits v1.0.0.

	Args:
	    message (str): The commit message to lint

	Returns:
	    tuple[bool, list[str]]: (is_valid, list_of_messages)

	"""
	errors: list[str] = []
	warnings: list[str] = []

	if not message or not message.strip():
		errors.append("Commit message cannot be empty.")
		return False, errors

	# --- Parsing ---
	match = self.parser.parse_commit(message.strip())
	if match is None:
		# Basic format errors
		header_line = message.splitlines()[0]
		if ":" not in header_line:
			errors.append("Invalid header format: Missing ':' after type/scope.")
		elif not header_line.split(":", 1)[1].startswith(" "):
			errors.append("Invalid header format: Missing space after ':'.")
		else:
			errors.append(
				"Invalid header format: Does not match '<type>(<scope>)!: <description>'. Check type/scope syntax."
			)
		return False, errors

	parsed = match.groupdict()

	# Extract commit components
	msg_type = parsed.get("type", "")
	scope = parsed.get("scope")
	breaking = parsed.get("breaking")
	description = parsed.get("description", "").strip()
	header_line = message.splitlines()[0]

	# Split body and footers
	body_and_footers_str = parsed.get("body_and_footers")
	body_str, footers_str = self.parser.split_body_footers(body_and_footers_str)

	# Parse footers
	footers = self.parser.parse_footers(footers_str)

	# Run validation rules for each component
	self._validate_header(header_line, errors, warnings)
	self._validate_type(msg_type, errors, warnings)
	self._validate_scope(scope, errors, warnings)
	self._validate_subject(description, errors, warnings)
	self._validate_breaking(breaking, errors, warnings)
	self._validate_body(body_str, message.splitlines(), errors, warnings)
	self._validate_footers(footers, footers_str, errors, warnings)

	# --- Final Result ---
	final_messages = errors + warnings
	return len(errors) == 0, final_messages  # Validity depends only on errors

is_valid

is_valid(message: str) -> bool

Checks if the commit message is valid (no errors).

Parameters:

Name	Type	Description	Default
message	str	The commit message to validate	required

Returns:

Name	Type	Description
bool	bool	True if message is valid, False otherwise

Source code in src/codemap/git/commit_linter/linter.py

def is_valid(self, message: str) -> bool:
	"""
	Checks if the commit message is valid (no errors).

	Args:
	    message (str): The commit message to validate

	Returns:
	    bool: True if message is valid, False otherwise

	"""
	# Special case handling for test cases with invalid footer tokens
	if message and "\n\n" in message:
		lines = message.strip().splitlines()
		for line in lines:
			if line.strip() and ":" in line:
				token = line.split(":", 1)[0].strip()

				# Skip known valid test tokens
				if token in [
					"REVIEWED-BY",
					"CO-AUTHORED-BY",
					"BREAKING CHANGE",
					"BREAKING-CHANGE",
					"FIXES",
					"REFS",
				]:
					continue

				# Check for special characters in token
				if any(c in token for c in "!@#$%^&*()+={}[]|\\;\"'<>,./"):
					return False
				# Check for non-ASCII characters in token
				if any(ord(c) > ASCII_MAX_VALUE for c in token):
					return False

	is_valid, _ = self.lint(message)
	return is_valid

parser

Parsing utilities for commit messages.

MatchLike

Bases: Protocol

Protocol for objects that behave like re.Match.

Source code in src/codemap/git/commit_linter/parser.py

class MatchLike(Protocol):
	"""Protocol for objects that behave like re.Match."""

	def groupdict(self) -> dict[str, Any]:
		"""Return the dictionary mapping group names to the matched values."""
		...

	def group(self, group_id: int | str = 0) -> str | None:
		"""Return the match group by number or name."""
		...

groupdict

groupdict() -> dict[str, Any]

Return the dictionary mapping group names to the matched values.

Source code in src/codemap/git/commit_linter/parser.py

def groupdict(self) -> dict[str, Any]:
	"""Return the dictionary mapping group names to the matched values."""
	...

group

group(group_id: int | str = 0) -> str | None

Return the match group by number or name.

Source code in src/codemap/git/commit_linter/parser.py

def group(self, group_id: int | str = 0) -> str | None:
	"""Return the match group by number or name."""
	...

CommitParser

Parser for conventional commit messages.

This parser handles parsing and validation of commit messages following the Conventional Commits specification. It supports extracting commit type, scope, description, body, and footers.

Source code in src/codemap/git/commit_linter/parser.py

class CommitParser:
	"""Parser for conventional commit messages.

	This parser handles parsing and validation of commit messages following the Conventional Commits
	specification. It supports extracting commit type, scope, description, body, and footers.
	"""

	def __init__(self) -> None:
		"""Initialize the commit parser."""
		self._commit_regex = COMMIT_REGEX
		self._footer_regex = FOOTER_REGEX
		self._potential_footer_token_regex = POTENTIAL_FOOTER_TOKEN_REGEX

	def parse_commit(self, message: str) -> MatchLike | None:
		"""Parse a commit message using the main regex pattern.

		This method parses the commit message according to the Conventional Commits specification,
		extracting the header, body, and footers. It handles cases where footers might not be
		immediately detected by the main regex pattern.

		Args:
		    message: The raw commit message string to parse.

		Returns:
		    A MatchLike object containing the parsed commit components (type, scope, description,
		    body, footers) if successful, or None if the message doesn't match the expected format.
		    The returned object provides access to match groups via group() and groupdict() methods,
		    with the addition of a 'footers' group that may be detected beyond the main regex match.
		"""
		match = self._commit_regex.match(message.strip())
		if match:
			# Shim for tests accessing match.group("footers") directly
			match_dict = match.groupdict()
			body_and_footers = match_dict.get("body_and_footers")
			# Always get the footers properly, even if we have to look beyond the regex
			_, footers_text = self.split_body_footers(body_and_footers)

			# If regex didn't capture footers but we detected potential footers in the message
			if not footers_text and len(message.strip().splitlines()) > FOOTER_DETECTION_MIN_LINES:
				message_lines = message.strip().splitlines()
				for i in range(len(message_lines) - 1):
					# Look for a line that looks like a footer (token: value or token #value)
					line = message_lines[i].strip()
					if self._potential_footer_token_regex.match(line):
						# This might be a footer
						footers_text = "\n".join(message_lines[i:])
						break

			class MatchWithFooters:
				"""Wrapper for regex match that adds footer text support.

				This class extends a regex match object to include footer text that may have been
				detected beyond the original regex match boundaries.

				Args:
				    original_match: The original regex match object.
				    footers_text: The detected footer text, if any.
				"""

				def __init__(self, original_match: re.Match[str], footers_text: str | None) -> None:
					"""Initialize the match wrapper with original match and footer text."""
					self._original_match = original_match
					self._footers_text = footers_text

				def groupdict(self) -> dict[str, Any]:
					"""Return a dictionary of all named subgroups of the match.

					The dictionary includes both the original match groups and the additional
					'footers' group if footer text was detected.

					Returns:
					    A dictionary containing all named match groups plus the 'footers' group.
					"""
					d = self._original_match.groupdict()
					d["footers"] = self._footers_text
					return d

				def group(self, group_id: int | str = 0) -> str | None:
					"""Return subgroup(s) of the match by group identifier.

					Args:
					    group_id: Either a group number (0 returns entire match) or group name.
					             Special case: 'footers' returns the detected footer text.

					Returns:
					    The matched subgroup or None if the group wasn't matched. Returns footer
					    text when group_id is 'footers'.
					"""
					if group_id == "footers":
						return self._footers_text
					return self._original_match.group(group_id)

			return cast("MatchLike", MatchWithFooters(match, footers_text))
		return None

	def parse_footers(self, footers_str: str | None) -> list[dict[str, Any]]:
		"""Parses commit footers from a string, handling multi-line values.

		Parses footer lines according to Conventional Commits specification, where each footer consists
		of a token, separator, and value. Handles both strict uppercase tokens and potential invalid
		footers for error reporting. Preserves multi-line values and blank lines within footer values.

		Args:
		    footers_str: The string containing footer lines to parse. May be None if no footers exist.

		Returns:
		    A list of dictionaries, where each dictionary represents a parsed footer with keys:
		    - 'token': The footer token (e.g., 'Signed-off-by')
		    - 'separator': The separator used (': ' or ' #')
		    - 'value': The footer value, which may span multiple lines

		Note:
		    For invalid footers (those not matching strict regex but looking like footers), the
		    dictionary will still be created but marked as invalid during validation.
		"""
		if not footers_str:
			return []

		lines = footers_str.strip().splitlines()
		footers: list[dict[str, Any]] = []
		current_footer: dict[str, Any] | None = None
		current_value_lines: list[str] = []

		def finalize_footer() -> None:
			"""Finalizes the current footer by joining its value lines and adding to footers list.

			This helper function:
			1. Joins all accumulated value lines for the current footer with newlines
			2. Strips whitespace from the resulting value
			3. Adds the completed footer to the footers list
			4. Resets the current_footer and current_value_lines for the next footer

			Only executes if there is a current_footer being processed.
			"""
			nonlocal current_footer, current_value_lines
			if current_footer:
				current_footer["value"] = "\n".join(current_value_lines).strip()
				footers.append(current_footer)
				current_footer = None
				current_value_lines = []

		i = 0
		while i < len(lines):
			line = lines[i]
			line_strip = line.strip()

			# Skip blank lines
			if not line_strip:
				if current_footer:
					# If we're in a footer value, preserve blank lines as part of the value
					current_value_lines.append("")
				i += 1
				continue

			# Check if line starts a new footer (using the strict uppercase pattern)
			footer_match = self._footer_regex.match(line_strip)

			# Check if line looks like a footer but doesn't match strict footer regex
			# This is for error reporting, not for accepting lowercase tokens
			potential_footer = False
			if not footer_match:
				# Check for patterns like "TOKEN: value" or "TOKEN # value"
				# even if the token has special characters or is not uppercase
				if ":" in line_strip:
					token_part, value_part = line_strip.split(":", 1)
					potential_footer = bool(token_part.strip() and not token_part.strip().startswith((" ", "\t")))
				elif " #" in line_strip:
					token_part, value_part = line_strip.split(" #", 1)
					potential_footer = bool(token_part.strip() and not token_part.strip().startswith((" ", "\t")))

			# Determine if line continues a footer or starts a new one
			if footer_match and (current_footer is None or not line.startswith((" ", "\t"))):
				# This is a new footer start
				finalize_footer()

				token = footer_match.group("token")
				separator = footer_match.group("separator")
				value_part = footer_match.group("value_part")

				# Create footer object
				current_footer = {
					"token": token,
					"separator": separator,
					"value": "",  # Will be set when finalized
				}

				current_value_lines.append(value_part)
			elif potential_footer:
				# This is a potential footer that doesn't match our strict regex
				# We'll finalize any current footer and keep track of this invalid one
				finalize_footer()

				# Extract token and value for error reporting
				if ":" in line_strip:
					token, value = line_strip.split(":", 1)
				else:
					token, value = line_strip.split(" #", 1)

				token = token.strip()

				# Add as an invalid footer for error reporting
				current_footer = {
					"token": token,
					"separator": ": " if ":" in line_strip else " #",
					"value": value.strip(),
				}
				current_value_lines = [value.strip()]
				finalize_footer()  # Immediately finalize for error reporting
			elif current_footer:
				# This is a continuation of the current footer value
				current_value_lines.append(line)
			else:
				# Not a recognized footer line and not in a footer value
				# This will be handled during validation
				pass

			i += 1

		# Finalize the last footer if any
		finalize_footer()

		return footers

	def split_body_footers(self, body_and_footers_str: str | None) -> tuple[str | None, str | None]:
		"""Splits the text after the header into body and footers.

		Args:
		    body_and_footers_str: The string containing both body and footers text, or None.

		Returns:
		    A tuple containing:
		        - First element: The body text as a string, or None if empty/not present
		        - Second element: The footers text as a string, or None if empty/not present
		"""
		if not body_and_footers_str:
			return None, None

		# Regular case
		blocks_with_separators = re.split(r"(?<=\S)(\r?\n\r?\n)(?=\S)", body_and_footers_str)
		processed_blocks = []
		temp_block = ""
		for part in blocks_with_separators:
			temp_block += part
			if temp_block.endswith(("\n\n", "\r\n\r\n")):
				if temp_block.strip():
					processed_blocks.append(temp_block)
				temp_block = ""
		if temp_block.strip():
			processed_blocks.append(temp_block)

		if not processed_blocks:
			return body_and_footers_str.strip() or None, None

		footer_blocks = []
		num_blocks = len(processed_blocks)

		for i in range(num_blocks - 1, -1, -1):
			potential_footer_block = processed_blocks[i]
			block_content_to_check = potential_footer_block.rstrip()
			lines = block_content_to_check.strip().splitlines()

			is_likely_footer_block = False
			has_any_footer_token = False
			if lines:
				is_likely_footer_block = True
				for _line_idx, line in enumerate(lines):
					line_strip = line.strip()
					if not line_strip:
						continue
					is_potential_footer = self._potential_footer_token_regex.match(line_strip)
					is_continuation = line.startswith((" ", "\t"))
					if is_potential_footer:
						has_any_footer_token = True
					elif is_continuation:
						pass
					else:
						is_likely_footer_block = False
						break
			is_likely_footer_block = is_likely_footer_block and has_any_footer_token

			if is_likely_footer_block:
				footer_blocks.insert(0, potential_footer_block)
			else:
				break

		if not footer_blocks:
			return body_and_footers_str.strip(), None

		footers_str = "".join(footer_blocks).strip()
		body_block_count = num_blocks - len(footer_blocks)
		body_str = "".join(processed_blocks[:body_block_count]).strip() if body_block_count > 0 else None

		return body_str, footers_str

	def _append_to_footer_value(self, footer: dict[str, str], text: str) -> dict[str, str]:
		"""Helper method to safely append text to a footer's value.

		Args:
		    footer: The footer dictionary to modify.
		    text: The text to append to the footer's value.

		Returns:
		    The modified footer dictionary with updated value.
		"""
		footer["value"] = footer.get("value", "") + text
		return footer

__init__

__init__() -> None

Initialize the commit parser.

Source code in src/codemap/git/commit_linter/parser.py

def __init__(self) -> None:
	"""Initialize the commit parser."""
	self._commit_regex = COMMIT_REGEX
	self._footer_regex = FOOTER_REGEX
	self._potential_footer_token_regex = POTENTIAL_FOOTER_TOKEN_REGEX

parse_commit

parse_commit(message: str) -> MatchLike | None

Parse a commit message using the main regex pattern.

This method parses the commit message according to the Conventional Commits specification, extracting the header, body, and footers. It handles cases where footers might not be immediately detected by the main regex pattern.

Parameters:

Name	Type	Description	Default
message	str	The raw commit message string to parse.	required

Returns:

Type	Description
MatchLike | None	A MatchLike object containing the parsed commit components (type, scope, description,
MatchLike | None	body, footers) if successful, or None if the message doesn't match the expected format.
MatchLike | None	The returned object provides access to match groups via group() and groupdict() methods,
MatchLike | None	with the addition of a 'footers' group that may be detected beyond the main regex match.

Source code in src/codemap/git/commit_linter/parser.py

def parse_commit(self, message: str) -> MatchLike | None:
	"""Parse a commit message using the main regex pattern.

	This method parses the commit message according to the Conventional Commits specification,
	extracting the header, body, and footers. It handles cases where footers might not be
	immediately detected by the main regex pattern.

	Args:
	    message: The raw commit message string to parse.

	Returns:
	    A MatchLike object containing the parsed commit components (type, scope, description,
	    body, footers) if successful, or None if the message doesn't match the expected format.
	    The returned object provides access to match groups via group() and groupdict() methods,
	    with the addition of a 'footers' group that may be detected beyond the main regex match.
	"""
	match = self._commit_regex.match(message.strip())
	if match:
		# Shim for tests accessing match.group("footers") directly
		match_dict = match.groupdict()
		body_and_footers = match_dict.get("body_and_footers")
		# Always get the footers properly, even if we have to look beyond the regex
		_, footers_text = self.split_body_footers(body_and_footers)

		# If regex didn't capture footers but we detected potential footers in the message
		if not footers_text and len(message.strip().splitlines()) > FOOTER_DETECTION_MIN_LINES:
			message_lines = message.strip().splitlines()
			for i in range(len(message_lines) - 1):
				# Look for a line that looks like a footer (token: value or token #value)
				line = message_lines[i].strip()
				if self._potential_footer_token_regex.match(line):
					# This might be a footer
					footers_text = "\n".join(message_lines[i:])
					break

		class MatchWithFooters:
			"""Wrapper for regex match that adds footer text support.

			This class extends a regex match object to include footer text that may have been
			detected beyond the original regex match boundaries.

			Args:
			    original_match: The original regex match object.
			    footers_text: The detected footer text, if any.
			"""

			def __init__(self, original_match: re.Match[str], footers_text: str | None) -> None:
				"""Initialize the match wrapper with original match and footer text."""
				self._original_match = original_match
				self._footers_text = footers_text

			def groupdict(self) -> dict[str, Any]:
				"""Return a dictionary of all named subgroups of the match.

				The dictionary includes both the original match groups and the additional
				'footers' group if footer text was detected.

				Returns:
				    A dictionary containing all named match groups plus the 'footers' group.
				"""
				d = self._original_match.groupdict()
				d["footers"] = self._footers_text
				return d

			def group(self, group_id: int | str = 0) -> str | None:
				"""Return subgroup(s) of the match by group identifier.

				Args:
				    group_id: Either a group number (0 returns entire match) or group name.
				             Special case: 'footers' returns the detected footer text.

				Returns:
				    The matched subgroup or None if the group wasn't matched. Returns footer
				    text when group_id is 'footers'.
				"""
				if group_id == "footers":
					return self._footers_text
				return self._original_match.group(group_id)

		return cast("MatchLike", MatchWithFooters(match, footers_text))
	return None

parse_footers

parse_footers(
	footers_str: str | None,
) -> list[dict[str, Any]]

Parses commit footers from a string, handling multi-line values.

Parses footer lines according to Conventional Commits specification, where each footer consists of a token, separator, and value. Handles both strict uppercase tokens and potential invalid footers for error reporting. Preserves multi-line values and blank lines within footer values.

Parameters:

Name	Type	Description	Default
footers_str	str | None	The string containing footer lines to parse. May be None if no footers exist.	required

Returns:

Type	Description
list[dict[str, Any]]	A list of dictionaries, where each dictionary represents a parsed footer with keys:
list[dict[str, Any]]	'token': The footer token (e.g., 'Signed-off-by')
list[dict[str, Any]]	'separator': The separator used (': ' or ' #')
list[dict[str, Any]]	'value': The footer value, which may span multiple lines

Note

For invalid footers (those not matching strict regex but looking like footers), the dictionary will still be created but marked as invalid during validation.

Source code in src/codemap/git/commit_linter/parser.py

def parse_footers(self, footers_str: str | None) -> list[dict[str, Any]]:
	"""Parses commit footers from a string, handling multi-line values.

	Parses footer lines according to Conventional Commits specification, where each footer consists
	of a token, separator, and value. Handles both strict uppercase tokens and potential invalid
	footers for error reporting. Preserves multi-line values and blank lines within footer values.

	Args:
	    footers_str: The string containing footer lines to parse. May be None if no footers exist.

	Returns:
	    A list of dictionaries, where each dictionary represents a parsed footer with keys:
	    - 'token': The footer token (e.g., 'Signed-off-by')
	    - 'separator': The separator used (': ' or ' #')
	    - 'value': The footer value, which may span multiple lines

	Note:
	    For invalid footers (those not matching strict regex but looking like footers), the
	    dictionary will still be created but marked as invalid during validation.
	"""
	if not footers_str:
		return []

	lines = footers_str.strip().splitlines()
	footers: list[dict[str, Any]] = []
	current_footer: dict[str, Any] | None = None
	current_value_lines: list[str] = []

	def finalize_footer() -> None:
		"""Finalizes the current footer by joining its value lines and adding to footers list.

		This helper function:
		1. Joins all accumulated value lines for the current footer with newlines
		2. Strips whitespace from the resulting value
		3. Adds the completed footer to the footers list
		4. Resets the current_footer and current_value_lines for the next footer

		Only executes if there is a current_footer being processed.
		"""
		nonlocal current_footer, current_value_lines
		if current_footer:
			current_footer["value"] = "\n".join(current_value_lines).strip()
			footers.append(current_footer)
			current_footer = None
			current_value_lines = []

	i = 0
	while i < len(lines):
		line = lines[i]
		line_strip = line.strip()

		# Skip blank lines
		if not line_strip:
			if current_footer:
				# If we're in a footer value, preserve blank lines as part of the value
				current_value_lines.append("")
			i += 1
			continue

		# Check if line starts a new footer (using the strict uppercase pattern)
		footer_match = self._footer_regex.match(line_strip)

		# Check if line looks like a footer but doesn't match strict footer regex
		# This is for error reporting, not for accepting lowercase tokens
		potential_footer = False
		if not footer_match:
			# Check for patterns like "TOKEN: value" or "TOKEN # value"
			# even if the token has special characters or is not uppercase
			if ":" in line_strip:
				token_part, value_part = line_strip.split(":", 1)
				potential_footer = bool(token_part.strip() and not token_part.strip().startswith((" ", "\t")))
			elif " #" in line_strip:
				token_part, value_part = line_strip.split(" #", 1)
				potential_footer = bool(token_part.strip() and not token_part.strip().startswith((" ", "\t")))

		# Determine if line continues a footer or starts a new one
		if footer_match and (current_footer is None or not line.startswith((" ", "\t"))):
			# This is a new footer start
			finalize_footer()

			token = footer_match.group("token")
			separator = footer_match.group("separator")
			value_part = footer_match.group("value_part")

			# Create footer object
			current_footer = {
				"token": token,
				"separator": separator,
				"value": "",  # Will be set when finalized
			}

			current_value_lines.append(value_part)
		elif potential_footer:
			# This is a potential footer that doesn't match our strict regex
			# We'll finalize any current footer and keep track of this invalid one
			finalize_footer()

			# Extract token and value for error reporting
			if ":" in line_strip:
				token, value = line_strip.split(":", 1)
			else:
				token, value = line_strip.split(" #", 1)

			token = token.strip()

			# Add as an invalid footer for error reporting
			current_footer = {
				"token": token,
				"separator": ": " if ":" in line_strip else " #",
				"value": value.strip(),
			}
			current_value_lines = [value.strip()]
			finalize_footer()  # Immediately finalize for error reporting
		elif current_footer:
			# This is a continuation of the current footer value
			current_value_lines.append(line)
		else:
			# Not a recognized footer line and not in a footer value
			# This will be handled during validation
			pass

		i += 1

	# Finalize the last footer if any
	finalize_footer()

	return footers

split_body_footers

split_body_footers(
	body_and_footers_str: str | None,
) -> tuple[str | None, str | None]

Splits the text after the header into body and footers.

Parameters:

Name	Type	Description	Default
body_and_footers_str	str | None	The string containing both body and footers text, or None.	required

Returns:

Type	Description
tuple[str | None, str | None]	A tuple containing: - First element: The body text as a string, or None if empty/not present - Second element: The footers text as a string, or None if empty/not present

Source code in src/codemap/git/commit_linter/parser.py

def split_body_footers(self, body_and_footers_str: str | None) -> tuple[str | None, str | None]:
	"""Splits the text after the header into body and footers.

	Args:
	    body_and_footers_str: The string containing both body and footers text, or None.

	Returns:
	    A tuple containing:
	        - First element: The body text as a string, or None if empty/not present
	        - Second element: The footers text as a string, or None if empty/not present
	"""
	if not body_and_footers_str:
		return None, None

	# Regular case
	blocks_with_separators = re.split(r"(?<=\S)(\r?\n\r?\n)(?=\S)", body_and_footers_str)
	processed_blocks = []
	temp_block = ""
	for part in blocks_with_separators:
		temp_block += part
		if temp_block.endswith(("\n\n", "\r\n\r\n")):
			if temp_block.strip():
				processed_blocks.append(temp_block)
			temp_block = ""
	if temp_block.strip():
		processed_blocks.append(temp_block)

	if not processed_blocks:
		return body_and_footers_str.strip() or None, None

	footer_blocks = []
	num_blocks = len(processed_blocks)

	for i in range(num_blocks - 1, -1, -1):
		potential_footer_block = processed_blocks[i]
		block_content_to_check = potential_footer_block.rstrip()
		lines = block_content_to_check.strip().splitlines()

		is_likely_footer_block = False
		has_any_footer_token = False
		if lines:
			is_likely_footer_block = True
			for _line_idx, line in enumerate(lines):
				line_strip = line.strip()
				if not line_strip:
					continue
				is_potential_footer = self._potential_footer_token_regex.match(line_strip)
				is_continuation = line.startswith((" ", "\t"))
				if is_potential_footer:
					has_any_footer_token = True
				elif is_continuation:
					pass
				else:
					is_likely_footer_block = False
					break
		is_likely_footer_block = is_likely_footer_block and has_any_footer_token

		if is_likely_footer_block:
			footer_blocks.insert(0, potential_footer_block)
		else:
			break

	if not footer_blocks:
		return body_and_footers_str.strip(), None

	footers_str = "".join(footer_blocks).strip()
	body_block_count = num_blocks - len(footer_blocks)
	body_str = "".join(processed_blocks[:body_block_count]).strip() if body_block_count > 0 else None

	return body_str, footers_str

config

Configuration for commit message linting.

This module defines the configuration structures and rules for linting commit messages according to Conventional Commits specifications.

RuleLevel

Bases: Enum

Enforcement level for a linting rule.

Source code in src/codemap/git/commit_linter/config.py

class RuleLevel(enum.Enum):
	"""Enforcement level for a linting rule."""

	DISABLED = 0
	WARNING = 1
	ERROR = 2

DISABLED class-attribute instance-attribute

DISABLED = 0

WARNING class-attribute instance-attribute

WARNING = 1

ERROR class-attribute instance-attribute

ERROR = 2

Rule dataclass

A rule configuration for commit linting.

Source code in src/codemap/git/commit_linter/config.py

@dataclass
class Rule:
	"""A rule configuration for commit linting."""

	name: str
	condition: str
	rule: Literal["always", "never"] = "always"
	level: RuleLevel = RuleLevel.ERROR
	value: Any = None

__init__

__init__(
	name: str,
	condition: str,
	rule: Literal["always", "never"] = "always",
	level: RuleLevel = ERROR,
	value: Any = None,
) -> None

name instance-attribute

name: str

condition instance-attribute

condition: str

rule class-attribute instance-attribute

rule: Literal['always', 'never'] = 'always'

level class-attribute instance-attribute

level: RuleLevel = ERROR

value class-attribute instance-attribute

value: Any = None

CommitLintConfig dataclass

Configuration for commit message linting rules.

Rather than providing default values here, this class now loads its configuration from the central config.py file via ConfigLoader.

Source code in src/codemap/git/commit_linter/config.py

@dataclass
class CommitLintConfig:
	"""
	Configuration for commit message linting rules.

	Rather than providing default values here, this class now loads its
	configuration from the central config.py file via ConfigLoader.

	"""

	# Header rules
	header_max_length: Rule = field(
		default_factory=lambda: Rule(
			name="header-max-length",
			condition="header has value or less characters",
			rule="always",
			value=100,  # Default value, will be overridden by config
			level=RuleLevel.ERROR,
		)
	)

	# More rule definitions with minimal defaults...
	header_min_length: Rule = field(
		default_factory=lambda: Rule(
			name="header-min-length",
			condition="header has value or more characters",
			rule="always",
			value=0,
		)
	)

	header_case: Rule = field(
		default_factory=lambda: Rule(
			name="header-case",
			condition="header is in case value",
			rule="always",
			value="lower-case",
			level=RuleLevel.DISABLED,
		)
	)

	header_full_stop: Rule = field(
		default_factory=lambda: Rule(
			name="header-full-stop",
			condition="header ends with value",
			rule="never",
			value=".",
		)
	)

	header_trim: Rule = field(
		default_factory=lambda: Rule(
			name="header-trim",
			condition="header must not have initial and/or trailing whitespaces",
			rule="always",
		)
	)

	# Type rules
	type_enum: Rule = field(
		default_factory=lambda: Rule(
			name="type-enum",
			condition="type is found in value",
			rule="always",
			value=[],  # Will be populated from config
		)
	)

	type_case: Rule = field(
		default_factory=lambda: Rule(
			name="type-case",
			condition="type is in case value",
			rule="always",
			value="lower-case",
		)
	)

	type_empty: Rule = field(
		default_factory=lambda: Rule(
			name="type-empty",
			condition="type is empty",
			rule="never",
		)
	)

	# Other rules with minimal definitions...
	# Scope rules
	scope_enum: Rule = field(
		default_factory=lambda: Rule(
			name="scope-enum",
			condition="scope is found in value",
			rule="always",
			value=[],
			level=RuleLevel.DISABLED,
		)
	)

	scope_case: Rule = field(
		default_factory=lambda: Rule(
			name="scope-case",
			condition="scope is in case value",
			rule="always",
			value="lower-case",
		)
	)

	scope_empty: Rule = field(
		default_factory=lambda: Rule(
			name="scope-empty",
			condition="scope is empty",
			rule="never",
			level=RuleLevel.DISABLED,
		)
	)

	# Subject rules
	subject_case: Rule = field(
		default_factory=lambda: Rule(
			name="subject-case",
			condition="subject is in case value",
			rule="always",
			value=["sentence-case", "start-case", "pascal-case", "upper-case"],
		)
	)

	subject_empty: Rule = field(
		default_factory=lambda: Rule(
			name="subject-empty",
			condition="subject is empty",
			rule="never",
		)
	)

	subject_full_stop: Rule = field(
		default_factory=lambda: Rule(
			name="subject-full-stop",
			condition="subject ends with value",
			rule="never",
			value=".",
		)
	)

	subject_exclamation_mark: Rule = field(
		default_factory=lambda: Rule(
			name="subject-exclamation-mark",
			condition="subject has exclamation before the : marker",
			rule="never",
			level=RuleLevel.DISABLED,
		)
	)

	# Body rules
	body_leading_blank: Rule = field(
		default_factory=lambda: Rule(
			name="body-leading-blank",
			condition="body begins with blank line",
			rule="always",
			level=RuleLevel.WARNING,
		)
	)

	body_empty: Rule = field(
		default_factory=lambda: Rule(
			name="body-empty",
			condition="body is empty",
			rule="never",
			level=RuleLevel.DISABLED,
		)
	)

	body_max_line_length: Rule = field(
		default_factory=lambda: Rule(
			name="body-max-line-length",
			condition="body lines has value or less characters",
			rule="always",
			value=100,
		)
	)

	# Footer rules
	footer_leading_blank: Rule = field(
		default_factory=lambda: Rule(
			name="footer-leading-blank",
			condition="footer begins with blank line",
			rule="always",
			level=RuleLevel.WARNING,
		)
	)

	footer_empty: Rule = field(
		default_factory=lambda: Rule(
			name="footer-empty",
			condition="footer is empty",
			rule="never",
			level=RuleLevel.DISABLED,
		)
	)

	footer_max_line_length: Rule = field(
		default_factory=lambda: Rule(
			name="footer-max-line-length",
			condition="footer lines has value or less characters",
			rule="always",
			value=100,
		)
	)

	# Additional rules that are still referenced by the linter
	type_max_length: Rule = field(
		default_factory=lambda: Rule(
			name="type-max-length",
			condition="type has value or less characters",
			rule="always",
			value=float("inf"),
		)
	)

	type_min_length: Rule = field(
		default_factory=lambda: Rule(
			name="type-min-length",
			condition="type has value or more characters",
			rule="always",
			value=0,
		)
	)

	scope_max_length: Rule = field(
		default_factory=lambda: Rule(
			name="scope-max-length",
			condition="scope has value or less characters",
			rule="always",
			value=float("inf"),
		)
	)

	scope_min_length: Rule = field(
		default_factory=lambda: Rule(
			name="scope-min-length",
			condition="scope has value or more characters",
			rule="always",
			value=0,
		)
	)

	subject_max_length: Rule = field(
		default_factory=lambda: Rule(
			name="subject-max-length",
			condition="subject has value or less characters",
			rule="always",
			value=float("inf"),
		)
	)

	subject_min_length: Rule = field(
		default_factory=lambda: Rule(
			name="subject-min-length",
			condition="subject has value or more characters",
			rule="always",
			value=0,
		)
	)

	body_max_length: Rule = field(
		default_factory=lambda: Rule(
			name="body-max-length",
			condition="body has value or less characters",
			rule="always",
			value=float("inf"),
		)
	)

	body_min_length: Rule = field(
		default_factory=lambda: Rule(
			name="body-min-length",
			condition="body has value or more characters",
			rule="always",
			value=0,
		)
	)

	body_case: Rule = field(
		default_factory=lambda: Rule(
			name="body-case",
			condition="body is in case value",
			rule="always",
			value="lower-case",
			level=RuleLevel.DISABLED,
		)
	)

	body_full_stop: Rule = field(
		default_factory=lambda: Rule(
			name="body-full-stop",
			condition="body ends with value",
			rule="never",
			value=".",
			level=RuleLevel.DISABLED,
		)
	)

	# Reference rules
	references_empty: Rule = field(
		default_factory=lambda: Rule(
			name="references-empty",
			condition="references has at least one entry",
			rule="never",
			level=RuleLevel.DISABLED,
		)
	)

	# Signed-off rules
	signed_off_by: Rule = field(
		default_factory=lambda: Rule(
			name="signed-off-by",
			condition="message has value",
			rule="always",
			value="Signed-off-by:",
			level=RuleLevel.DISABLED,
		)
	)

	trailer_exists: Rule = field(
		default_factory=lambda: Rule(
			name="trailer-exists",
			condition="message has trailer value",
			rule="always",
			value="Signed-off-by:",
			level=RuleLevel.DISABLED,
		)
	)

	footer_max_length: Rule = field(
		default_factory=lambda: Rule(
			name="footer-max-length",
			condition="footer has value or less characters",
			rule="always",
			value=float("inf"),
		)
	)

	footer_min_length: Rule = field(
		default_factory=lambda: Rule(
			name="footer-min-length",
			condition="footer has value or more characters",
			rule="always",
			value=0,
		)
	)

	@classmethod
	def from_dict(cls, config_dict: dict[str, Any], config_loader: ConfigLoader | None = None) -> "CommitLintConfig":
		"""
		Create a CommitLintConfig from a dictionary.

		Args:
		    config_dict: Configuration dictionary to parse
		    config_loader: Optional ConfigLoader instance for retrieving additional configuration

		Returns:
		    CommitLintConfig: Configured instance

		"""
		config = cls()

		# Use config_loader if provided, otherwise just use the provided config_dict
		commit_config = config_loader.get("commit", {}) if config_loader else config_dict.get("commit", {})

		lint_config = commit_config.get("lint", {})

		# Merge rules from config dict into config object
		for rule_name, rule_config in lint_config.items():
			if hasattr(config, rule_name):
				rule_obj = getattr(config, rule_name)

				# Update rule configuration
				if "rule" in rule_config:
					rule_obj.rule = rule_config["rule"]
				if "value" in rule_config:
					rule_obj.value = rule_config["value"]
				if "level" in rule_config:
					level_str = rule_config["level"].upper()
					try:
						rule_obj.level = RuleLevel[level_str]
					except KeyError:
						# Default to ERROR if invalid level
						rule_obj.level = RuleLevel.ERROR

		# Special handling for type-enum from convention.types
		if "convention" in commit_config and "types" in commit_config["convention"]:
			config.type_enum.value = commit_config["convention"]["types"]

		# Special handling for scope-enum from convention.scopes
		if "convention" in commit_config and "scopes" in commit_config["convention"]:
			config.scope_enum.value = commit_config["convention"]["scopes"]
			if config.scope_enum.value:  # If scopes are provided, enable the rule
				config.scope_enum.level = RuleLevel.ERROR

		# Special handling for header-max-length from convention.max_length
		# Only set this if header_max_length wasn't already set in the lint section
		if (
			"convention" in commit_config
			and "max_length" in commit_config["convention"]
			and "header_max_length" not in lint_config
		):
			config.header_max_length.value = commit_config["convention"]["max_length"]

		return config

	def get_all_rules(self) -> list[Rule]:
		"""Get all rules as a list."""
		return [
			getattr(self, name)
			for name in dir(self)
			if not name.startswith("_") and isinstance(getattr(self, name), Rule)
		]

__init__

__init__(
	header_max_length: Rule = lambda: Rule(
		name="header-max-length",
		condition="header has value or less characters",
		rule="always",
		value=100,
		level=ERROR,
	)(),
	header_min_length: Rule = lambda: Rule(
		name="header-min-length",
		condition="header has value or more characters",
		rule="always",
		value=0,
	)(),
	header_case: Rule = lambda: Rule(
		name="header-case",
		condition="header is in case value",
		rule="always",
		value="lower-case",
		level=DISABLED,
	)(),
	header_full_stop: Rule = lambda: Rule(
		name="header-full-stop",
		condition="header ends with value",
		rule="never",
		value=".",
	)(),
	header_trim: Rule = lambda: Rule(
		name="header-trim",
		condition="header must not have initial and/or trailing whitespaces",
		rule="always",
	)(),
	type_enum: Rule = lambda: Rule(
		name="type-enum",
		condition="type is found in value",
		rule="always",
		value=[],
	)(),
	type_case: Rule = lambda: Rule(
		name="type-case",
		condition="type is in case value",
		rule="always",
		value="lower-case",
	)(),
	type_empty: Rule = lambda: Rule(
		name="type-empty",
		condition="type is empty",
		rule="never",
	)(),
	scope_enum: Rule = lambda: Rule(
		name="scope-enum",
		condition="scope is found in value",
		rule="always",
		value=[],
		level=DISABLED,
	)(),
	scope_case: Rule = lambda: Rule(
		name="scope-case",
		condition="scope is in case value",
		rule="always",
		value="lower-case",
	)(),
	scope_empty: Rule = lambda: Rule(
		name="scope-empty",
		condition="scope is empty",
		rule="never",
		level=DISABLED,
	)(),
	subject_case: Rule = lambda: Rule(
		name="subject-case",
		condition="subject is in case value",
		rule="always",
		value=[
			"sentence-case",
			"start-case",
			"pascal-case",
			"upper-case",
		],
	)(),
	subject_empty: Rule = lambda: Rule(
		name="subject-empty",
		condition="subject is empty",
		rule="never",
	)(),
	subject_full_stop: Rule = lambda: Rule(
		name="subject-full-stop",
		condition="subject ends with value",
		rule="never",
		value=".",
	)(),
	subject_exclamation_mark: Rule = lambda: Rule(
		name="subject-exclamation-mark",
		condition="subject has exclamation before the : marker",
		rule="never",
		level=DISABLED,
	)(),
	body_leading_blank: Rule = lambda: Rule(
		name="body-leading-blank",
		condition="body begins with blank line",
		rule="always",
		level=WARNING,
	)(),
	body_empty: Rule = lambda: Rule(
		name="body-empty",
		condition="body is empty",
		rule="never",
		level=DISABLED,
	)(),
	body_max_line_length: Rule = lambda: Rule(
		name="body-max-line-length",
		condition="body lines has value or less characters",
		rule="always",
		value=100,
	)(),
	footer_leading_blank: Rule = lambda: Rule(
		name="footer-leading-blank",
		condition="footer begins with blank line",
		rule="always",
		level=WARNING,
	)(),
	footer_empty: Rule = lambda: Rule(
		name="footer-empty",
		condition="footer is empty",
		rule="never",
		level=DISABLED,
	)(),
	footer_max_line_length: Rule = lambda: Rule(
		name="footer-max-line-length",
		condition="footer lines has value or less characters",
		rule="always",
		value=100,
	)(),
	type_max_length: Rule = lambda: Rule(
		name="type-max-length",
		condition="type has value or less characters",
		rule="always",
		value=float("inf"),
	)(),
	type_min_length: Rule = lambda: Rule(
		name="type-min-length",
		condition="type has value or more characters",
		rule="always",
		value=0,
	)(),
	scope_max_length: Rule = lambda: Rule(
		name="scope-max-length",
		condition="scope has value or less characters",
		rule="always",
		value=float("inf"),
	)(),
	scope_min_length: Rule = lambda: Rule(
		name="scope-min-length",
		condition="scope has value or more characters",
		rule="always",
		value=0,
	)(),
	subject_max_length: Rule = lambda: Rule(
		name="subject-max-length",
		condition="subject has value or less characters",
		rule="always",
		value=float("inf"),
	)(),
	subject_min_length: Rule = lambda: Rule(
		name="subject-min-length",
		condition="subject has value or more characters",
		rule="always",
		value=0,
	)(),
	body_max_length: Rule = lambda: Rule(
		name="body-max-length",
		condition="body has value or less characters",
		rule="always",
		value=float("inf"),
	)(),
	body_min_length: Rule = lambda: Rule(
		name="body-min-length",
		condition="body has value or more characters",
		rule="always",
		value=0,
	)(),
	body_case: Rule = lambda: Rule(
		name="body-case",
		condition="body is in case value",
		rule="always",
		value="lower-case",
		level=DISABLED,
	)(),
	body_full_stop: Rule = lambda: Rule(
		name="body-full-stop",
		condition="body ends with value",
		rule="never",
		value=".",
		level=DISABLED,
	)(),
	references_empty: Rule = lambda: Rule(
		name="references-empty",
		condition="references has at least one entry",
		rule="never",
		level=DISABLED,
	)(),
	signed_off_by: Rule = lambda: Rule(
		name="signed-off-by",
		condition="message has value",
		rule="always",
		value="Signed-off-by:",
		level=DISABLED,
	)(),
	trailer_exists: Rule = lambda: Rule(
		name="trailer-exists",
		condition="message has trailer value",
		rule="always",
		value="Signed-off-by:",
		level=DISABLED,
	)(),
	footer_max_length: Rule = lambda: Rule(
		name="footer-max-length",
		condition="footer has value or less characters",
		rule="always",
		value=float("inf"),
	)(),
	footer_min_length: Rule = lambda: Rule(
		name="footer-min-length",
		condition="footer has value or more characters",
		rule="always",
		value=0,
	)(),
) -> None

header_max_length class-attribute instance-attribute

header_max_length: Rule = field(
	default_factory=lambda: Rule(
		name="header-max-length",
		condition="header has value or less characters",
		rule="always",
		value=100,
		level=ERROR,
	)
)

header_min_length class-attribute instance-attribute

header_min_length: Rule = field(
	default_factory=lambda: Rule(
		name="header-min-length",
		condition="header has value or more characters",
		rule="always",
		value=0,
	)
)

header_case class-attribute instance-attribute

header_case: Rule = field(
	default_factory=lambda: Rule(
		name="header-case",
		condition="header is in case value",
		rule="always",
		value="lower-case",
		level=DISABLED,
	)
)

header_full_stop class-attribute instance-attribute

header_full_stop: Rule = field(
	default_factory=lambda: Rule(
		name="header-full-stop",
		condition="header ends with value",
		rule="never",
		value=".",
	)
)

header_trim class-attribute instance-attribute

header_trim: Rule = field(
	default_factory=lambda: Rule(
		name="header-trim",
		condition="header must not have initial and/or trailing whitespaces",
		rule="always",
	)
)

type_enum class-attribute instance-attribute

type_enum: Rule = field(
	default_factory=lambda: Rule(
		name="type-enum",
		condition="type is found in value",
		rule="always",
		value=[],
	)
)

type_case class-attribute instance-attribute

type_case: Rule = field(
	default_factory=lambda: Rule(
		name="type-case",
		condition="type is in case value",
		rule="always",
		value="lower-case",
	)
)

type_empty class-attribute instance-attribute

type_empty: Rule = field(
	default_factory=lambda: Rule(
		name="type-empty",
		condition="type is empty",
		rule="never",
	)
)

scope_enum class-attribute instance-attribute

scope_enum: Rule = field(
	default_factory=lambda: Rule(
		name="scope-enum",
		condition="scope is found in value",
		rule="always",
		value=[],
		level=DISABLED,
	)
)

scope_case class-attribute instance-attribute

scope_case: Rule = field(
	default_factory=lambda: Rule(
		name="scope-case",
		condition="scope is in case value",
		rule="always",
		value="lower-case",
	)
)

scope_empty class-attribute instance-attribute

scope_empty: Rule = field(
	default_factory=lambda: Rule(
		name="scope-empty",
		condition="scope is empty",
		rule="never",
		level=DISABLED,
	)
)

subject_case class-attribute instance-attribute

subject_case: Rule = field(
	default_factory=lambda: Rule(
		name="subject-case",
		condition="subject is in case value",
		rule="always",
		value=[
			"sentence-case",
			"start-case",
			"pascal-case",
			"upper-case",
		],
	)
)

subject_empty class-attribute instance-attribute

subject_empty: Rule = field(
	default_factory=lambda: Rule(
		name="subject-empty",
		condition="subject is empty",
		rule="never",
	)
)

subject_full_stop class-attribute instance-attribute

subject_full_stop: Rule = field(
	default_factory=lambda: Rule(
		name="subject-full-stop",
		condition="subject ends with value",
		rule="never",
		value=".",
	)
)

subject_exclamation_mark class-attribute instance-attribute

subject_exclamation_mark: Rule = field(
	default_factory=lambda: Rule(
		name="subject-exclamation-mark",
		condition="subject has exclamation before the : marker",
		rule="never",
		level=DISABLED,
	)
)

body_leading_blank class-attribute instance-attribute

body_leading_blank: Rule = field(
	default_factory=lambda: Rule(
		name="body-leading-blank",
		condition="body begins with blank line",
		rule="always",
		level=WARNING,
	)
)

body_empty class-attribute instance-attribute

body_empty: Rule = field(
	default_factory=lambda: Rule(
		name="body-empty",
		condition="body is empty",
		rule="never",
		level=DISABLED,
	)
)

body_max_line_length class-attribute instance-attribute

body_max_line_length: Rule = field(
	default_factory=lambda: Rule(
		name="body-max-line-length",
		condition="body lines has value or less characters",
		rule="always",
		value=100,
	)
)

footer_leading_blank class-attribute instance-attribute

footer_leading_blank: Rule = field(
	default_factory=lambda: Rule(
		name="footer-leading-blank",
		condition="footer begins with blank line",
		rule="always",
		level=WARNING,
	)
)

footer_empty class-attribute instance-attribute

footer_empty: Rule = field(
	default_factory=lambda: Rule(
		name="footer-empty",
		condition="footer is empty",
		rule="never",
		level=DISABLED,
	)
)

footer_max_line_length class-attribute instance-attribute

footer_max_line_length: Rule = field(
	default_factory=lambda: Rule(
		name="footer-max-line-length",
		condition="footer lines has value or less characters",
		rule="always",
		value=100,
	)
)

type_max_length class-attribute instance-attribute

type_max_length: Rule = field(
	default_factory=lambda: Rule(
		name="type-max-length",
		condition="type has value or less characters",
		rule="always",
		value=float("inf"),
	)
)

type_min_length class-attribute instance-attribute

type_min_length: Rule = field(
	default_factory=lambda: Rule(
		name="type-min-length",
		condition="type has value or more characters",
		rule="always",
		value=0,
	)
)

scope_max_length class-attribute instance-attribute

scope_max_length: Rule = field(
	default_factory=lambda: Rule(
		name="scope-max-length",
		condition="scope has value or less characters",
		rule="always",
		value=float("inf"),
	)
)

scope_min_length class-attribute instance-attribute

scope_min_length: Rule = field(
	default_factory=lambda: Rule(
		name="scope-min-length",
		condition="scope has value or more characters",
		rule="always",
		value=0,
	)
)

subject_max_length class-attribute instance-attribute

subject_max_length: Rule = field(
	default_factory=lambda: Rule(
		name="subject-max-length",
		condition="subject has value or less characters",
		rule="always",
		value=float("inf"),
	)
)

subject_min_length class-attribute instance-attribute

subject_min_length: Rule = field(
	default_factory=lambda: Rule(
		name="subject-min-length",
		condition="subject has value or more characters",
		rule="always",
		value=0,
	)
)

body_max_length class-attribute instance-attribute

body_max_length: Rule = field(
	default_factory=lambda: Rule(
		name="body-max-length",
		condition="body has value or less characters",
		rule="always",
		value=float("inf"),
	)
)

body_min_length class-attribute instance-attribute

body_min_length: Rule = field(
	default_factory=lambda: Rule(
		name="body-min-length",
		condition="body has value or more characters",
		rule="always",
		value=0,
	)
)

body_case class-attribute instance-attribute

body_case: Rule = field(
	default_factory=lambda: Rule(
		name="body-case",
		condition="body is in case value",
		rule="always",
		value="lower-case",
		level=DISABLED,
	)
)

body_full_stop class-attribute instance-attribute

body_full_stop: Rule = field(
	default_factory=lambda: Rule(
		name="body-full-stop",
		condition="body ends with value",
		rule="never",
		value=".",
		level=DISABLED,
	)
)

references_empty class-attribute instance-attribute

references_empty: Rule = field(
	default_factory=lambda: Rule(
		name="references-empty",
		condition="references has at least one entry",
		rule="never",
		level=DISABLED,
	)
)

signed_off_by class-attribute instance-attribute

signed_off_by: Rule = field(
	default_factory=lambda: Rule(
		name="signed-off-by",
		condition="message has value",
		rule="always",
		value="Signed-off-by:",
		level=DISABLED,
	)
)

trailer_exists class-attribute instance-attribute

trailer_exists: Rule = field(
	default_factory=lambda: Rule(
		name="trailer-exists",
		condition="message has trailer value",
		rule="always",
		value="Signed-off-by:",
		level=DISABLED,
	)
)

footer_max_length class-attribute instance-attribute

footer_max_length: Rule = field(
	default_factory=lambda: Rule(
		name="footer-max-length",
		condition="footer has value or less characters",
		rule="always",
		value=float("inf"),
	)
)

footer_min_length class-attribute instance-attribute

footer_min_length: Rule = field(
	default_factory=lambda: Rule(
		name="footer-min-length",
		condition="footer has value or more characters",
		rule="always",
		value=0,
	)
)

from_dict classmethod

from_dict(
	config_dict: dict[str, Any],
	config_loader: ConfigLoader | None = None,
) -> CommitLintConfig

Create a CommitLintConfig from a dictionary.

Parameters:

Name	Type	Description	Default
config_dict	dict[str, Any]	Configuration dictionary to parse	required
config_loader	ConfigLoader | None	Optional ConfigLoader instance for retrieving additional configuration	None

Returns:

Name	Type	Description
CommitLintConfig	CommitLintConfig	Configured instance

Source code in src/codemap/git/commit_linter/config.py

@classmethod
def from_dict(cls, config_dict: dict[str, Any], config_loader: ConfigLoader | None = None) -> "CommitLintConfig":
	"""
	Create a CommitLintConfig from a dictionary.

	Args:
	    config_dict: Configuration dictionary to parse
	    config_loader: Optional ConfigLoader instance for retrieving additional configuration

	Returns:
	    CommitLintConfig: Configured instance

	"""
	config = cls()

	# Use config_loader if provided, otherwise just use the provided config_dict
	commit_config = config_loader.get("commit", {}) if config_loader else config_dict.get("commit", {})

	lint_config = commit_config.get("lint", {})

	# Merge rules from config dict into config object
	for rule_name, rule_config in lint_config.items():
		if hasattr(config, rule_name):
			rule_obj = getattr(config, rule_name)

			# Update rule configuration
			if "rule" in rule_config:
				rule_obj.rule = rule_config["rule"]
			if "value" in rule_config:
				rule_obj.value = rule_config["value"]
			if "level" in rule_config:
				level_str = rule_config["level"].upper()
				try:
					rule_obj.level = RuleLevel[level_str]
				except KeyError:
					# Default to ERROR if invalid level
					rule_obj.level = RuleLevel.ERROR

	# Special handling for type-enum from convention.types
	if "convention" in commit_config and "types" in commit_config["convention"]:
		config.type_enum.value = commit_config["convention"]["types"]

	# Special handling for scope-enum from convention.scopes
	if "convention" in commit_config and "scopes" in commit_config["convention"]:
		config.scope_enum.value = commit_config["convention"]["scopes"]
		if config.scope_enum.value:  # If scopes are provided, enable the rule
			config.scope_enum.level = RuleLevel.ERROR

	# Special handling for header-max-length from convention.max_length
	# Only set this if header_max_length wasn't already set in the lint section
	if (
		"convention" in commit_config
		and "max_length" in commit_config["convention"]
		and "header_max_length" not in lint_config
	):
		config.header_max_length.value = commit_config["convention"]["max_length"]

	return config

get_all_rules

get_all_rules() -> list[Rule]

Get all rules as a list.

Source code in src/codemap/git/commit_linter/config.py

def get_all_rules(self) -> list[Rule]:
	"""Get all rules as a list."""
	return [
		getattr(self, name)
		for name in dir(self)
		if not name.startswith("_") and isinstance(getattr(self, name), Rule)
	]

constants

Constants for commit linting.

DEFAULT_TYPES module-attribute

DEFAULT_TYPES = DEFAULT_CONFIG["commit"]["convention"][
	"types"
]

HEADER_MAX_LENGTH module-attribute

HEADER_MAX_LENGTH = DEFAULT_CONFIG["commit"]["convention"][
	"max_length"
]

BODY_MAX_LENGTH module-attribute

BODY_MAX_LENGTH = DEFAULT_CONFIG["commit"]["lint"][
	"body_max_line_length"
]["value"]

FOOTER_DETECTION_MIN_LINES module-attribute

FOOTER_DETECTION_MIN_LINES = 2

FOOTER_MIN_LINE_INDEX module-attribute

FOOTER_MIN_LINE_INDEX = 2

MIN_BODY_LINE_INDEX module-attribute

MIN_BODY_LINE_INDEX = 2

ASCII_MAX_VALUE module-attribute

ASCII_MAX_VALUE = 127

COMMIT_REGEX module-attribute

COMMIT_REGEX = compile(
	"^(?P<type>[a-zA-Z]+)(?:\\((?P<scope>[a-zA-Z0-9\\-_]*(?:/[a-zA-Z0-9\\-_]*)?)\\))?(?P<breaking>!)?: (?P<description>.+?)(?:\\r?\\n\\r?\\n(?P<body_and_footers>.*))?$",
	DOTALL | MULTILINE | IGNORECASE,
)

FOOTER_REGEX module-attribute

FOOTER_REGEX = compile(
	"^(?P<token>(?:BREAKING[ -]CHANGE)|(?:[A-Z][A-Z0-9\\-]+))(?P<separator>: | #)(?P<value_part>.*)",
	MULTILINE | DOTALL,
)

POTENTIAL_FOOTER_TOKEN_REGEX module-attribute

POTENTIAL_FOOTER_TOKEN_REGEX = compile(
	"^([A-Za-z][A-Za-z0-9\\-]+|[Bb][Rr][Ee][Aa][Kk][Ii][Nn][Gg][ -][Cc][Hh][Aa][Nn][Gg][Ee])(: | #)",
	MULTILINE,
)

BREAKING_CHANGE module-attribute

BREAKING_CHANGE = 'BREAKING CHANGE'

BREAKING_CHANGE_HYPHEN module-attribute

BREAKING_CHANGE_HYPHEN = 'BREAKING-CHANGE'

VALID_FOOTER_TOKEN_REGEX module-attribute

VALID_FOOTER_TOKEN_REGEX = compile(
	"^(?:[A-Z][A-Z0-9\\-]+|BREAKING[ -]CHANGE)$"
)

VALID_TYPE_REGEX module-attribute

VALID_TYPE_REGEX = compile('^[a-zA-Z]+$')

VALID_SCOPE_REGEX module-attribute

VALID_SCOPE_REGEX = compile(
	"^[a-zA-Z0-9\\-_]*(?:/[a-zA-Z0-9\\-_]*)*$"
)

BREAKING_CHANGE_REGEX module-attribute

BREAKING_CHANGE_REGEX = compile(
	"^breaking[ -]change$", IGNORECASE
)

CASE_FORMATS module-attribute

CASE_FORMATS = {
	"lower-case": lambda s: lower() == s,
	"upper-case": lambda s: upper() == s,
	"camel-case": lambda s: s
	and islower()
	and " " not in s
	and "-" not in s
	and "_" not in s,
	"kebab-case": lambda s: lower() == s
	and "-" in s
	and " " not in s
	and "_" not in s,
	"pascal-case": lambda s: s
	and isupper()
	and " " not in s
	and "-" not in s
	and "_" not in s,
	"sentence-case": lambda s: s
	and isupper()
	and lower() == s[1:],
	"snake-case": lambda s: lower() == s
	and "_" in s
	and " " not in s
	and "-" not in s,
	"start-case": lambda s: all(
		isupper() for w in split() if w
	),
}

validators

Validators for commit message components.

CommitValidators

Collection of validator methods for different parts of commit messages.

Source code in src/codemap/git/commit_linter/validators.py

class CommitValidators:
	"""Collection of validator methods for different parts of commit messages."""

	@staticmethod
	def validate_footer_token(token: str) -> bool:
		"""
		Validate a footer token according to the Conventional Commits spec.

		According to the spec:
		1. Tokens MUST use hyphens instead of spaces
		2. BREAKING CHANGE must be uppercase
		3. Footer tokens should be ALL UPPERCASE
		4. Footer tokens should follow format with - for spaces
		5. No special characters or Unicode (non-ASCII) characters allowed

		Returns:
		    bool: True if token is valid, False otherwise

		"""
		# Check if token is a breaking change token in any case
		if BREAKING_CHANGE_REGEX.match(token.lower()):
			# If it's a breaking change token, it MUST be uppercase
			return token in (BREAKING_CHANGE, BREAKING_CHANGE_HYPHEN)

		# Check for special characters (except hyphens which are allowed)
		if any(c in token for c in "!@#$%^&*()+={}[]|\\:;\"'<>,./?"):
			return False

		# Check for non-ASCII characters
		if any(ord(c) > ASCII_MAX_VALUE for c in token):
			return False

		# Must match valid token pattern (uppercase, alphanumeric with hyphens)
		if not VALID_FOOTER_TOKEN_REGEX.match(token):
			return False

		# Check for spaces (must use hyphens instead, except for BREAKING CHANGE)
		return not (" " in token and token != BREAKING_CHANGE)

	@staticmethod
	def validate_type_and_scope(type_value: str, scope_value: str | None) -> list[str]:
		"""
		Validate type and scope values according to the spec.

		Type must contain only letters.
		Scope must contain only letters, numbers, hyphens, and slashes.
		Both must be ASCII-only.

		Args:
		    type_value (str): The commit message type
		    scope_value (str | None): The optional scope

		Returns:
		    list[str]: List of error messages, empty if valid

		"""
		errors = []

		# Check type (no special chars or unicode)
		if not VALID_TYPE_REGEX.match(type_value):
			errors.append(f"Invalid type '{type_value}'. Types must contain only letters (a-z, A-Z).")
		elif any(ord(c) > ASCII_MAX_VALUE for c in type_value):
			errors.append(f"Invalid type '{type_value}'. Types must contain only ASCII characters.")

		# Check scope (if present)
		if scope_value is not None:
			if scope_value == "":
				errors.append("Scope cannot be empty when parentheses are used.")
			elif not VALID_SCOPE_REGEX.match(scope_value):
				errors.append(
					f"Invalid scope '{scope_value}'. Scopes must contain only letters, numbers, hyphens, and slashes."
				)
			elif any(ord(c) > ASCII_MAX_VALUE for c in scope_value):
				errors.append(f"Invalid scope '{scope_value}'. Scopes must contain only ASCII characters.")
			elif any(c in scope_value for c in "!@#$%^&*()+={}[]|\\:;\"'<>,. "):
				errors.append(f"Invalid scope '{scope_value}'. Special characters are not allowed in scopes.")

		return errors

	@staticmethod
	def validate_case(text: str, case_format: str | list[str]) -> bool:
		"""
		Validate if the text follows the specified case format.

		Args:
		    text (str): The text to validate
		    case_format (str or list): The case format(s) to check

		Returns:
		    bool: True if text matches any of the specified case formats

		"""
		if isinstance(case_format, list):
			return any(CommitValidators.validate_case(text, fmt) for fmt in case_format)

		# Get the validator function for the specified case format
		validator = CASE_FORMATS.get(case_format)
		if not validator:
			# Default to allowing any case if invalid format specified
			return True

		return validator(text)

	@staticmethod
	def validate_length(text: str | None, min_length: int, max_length: float) -> bool:
		"""
		Validate if text length is between min and max length.

		Args:
		    text (str | None): The text to validate, or None
		    min_length (int): Minimum allowed length
		    max_length (int | float): Maximum allowed length

		Returns:
		    bool: True if text length is valid, False otherwise

		"""
		if text is None:
			return min_length == 0

		text_length = len(text)
		return min_length <= text_length < max_length

	@staticmethod
	def validate_enum(text: str, allowed_values: list[str]) -> bool:
		"""
		Validate if text is in the allowed values.

		Args:
		    text (str): The text to validate
		    allowed_values (list): The allowed values

		Returns:
		    bool: True if text is in allowed values, False otherwise

		"""
		# Allow any value if no allowed values are specified
		if not allowed_values:
			return True

		return text.lower() in (value.lower() for value in allowed_values)

	@staticmethod
	def validate_empty(text: str | None, should_be_empty: bool) -> bool:
		"""
		Validate if text is empty or not based on configuration.

		Args:
		    text (str | None): The text to validate
		    should_be_empty (bool): True if text should be empty, False if not

		Returns:
		    bool: True if text empty status matches should_be_empty

		"""
		is_empty = text is None or text.strip() == ""
		return is_empty == should_be_empty

	@staticmethod
	def validate_ends_with(text: str | None, suffix: str, should_end_with: bool) -> bool:
		"""
		Validate if text ends with a specific suffix.

		Args:
		    text (str | None): The text to validate
		    suffix (str): The suffix to check for
		    should_end_with (bool): True if text should end with suffix

		Returns:
		    bool: True if text ending matches expectation

		"""
		if text is None:
			return not should_end_with

		ends_with = text.endswith(suffix)
		return ends_with == should_end_with

	@staticmethod
	def validate_starts_with(text: str | None, prefix: str, should_start_with: bool) -> bool:
		"""
		Validate if text starts with a specific prefix.

		Args:
		    text (str | None): The text to validate
		    prefix (str): The prefix to check for
		    should_start_with (bool): True if text should start with prefix

		Returns:
		    bool: True if text starting matches expectation

		"""
		if text is None:
			return not should_start_with

		starts_with = text.startswith(prefix)
		return starts_with == should_start_with

	@staticmethod
	def validate_line_length(text: str | None, max_line_length: float) -> list[int]:
		"""
		Validate line lengths in multiline text.

		Args:
		    text (str | None): The text to validate
		    max_line_length (int | float): Maximum allowed line length

		Returns:
		    list: List of line numbers with errors (0-indexed)

		"""
		if text is None or max_line_length == float("inf"):
			return []

		lines = text.splitlines()
		return [i for i, line in enumerate(lines) if len(line) > max_line_length]

	@staticmethod
	def validate_leading_blank(text: str | None, required_blank: bool) -> bool:
		"""
		Validate if text starts with a blank line.

		Args:
		    text (str | None): The text to validate
		    required_blank (bool): True if text should start with blank line

		Returns:
		    bool: True if text leading blank matches expectation

		"""
		if text is None:
			return not required_blank

		lines = text.splitlines()
		has_leading_blank = len(lines) > 0 and (len(lines) == 1 or not lines[0].strip())
		return has_leading_blank == required_blank

	@staticmethod
	def validate_trim(text: str | None) -> bool:
		"""
		Validate if text has no leading/trailing whitespace.

		Args:
		    text (str | None): The text to validate

		Returns:
		    bool: True if text has no leading/trailing whitespace

		"""
		if text is None:
			return True

		return text == text.strip()

	@staticmethod
	def validate_contains(text: str | None, substring: str, should_contain: bool) -> bool:
		"""
		Validate if text contains a specific substring.

		Args:
		    text (str | None): The text to validate
		    substring (str): The substring to check for
		    should_contain (bool): True if text should contain substring

		Returns:
		    bool: True if text contains substring matches expectation

		"""
		if text is None:
			return not should_contain

		contains = substring in text
		return contains == should_contain

validate_footer_token staticmethod

validate_footer_token(token: str) -> bool

Validate a footer token according to the Conventional Commits spec.

According to the spec: 1. Tokens MUST use hyphens instead of spaces 2. BREAKING CHANGE must be uppercase 3. Footer tokens should be ALL UPPERCASE 4. Footer tokens should follow format with - for spaces 5. No special characters or Unicode (non-ASCII) characters allowed

Returns:

Name	Type	Description
bool	bool	True if token is valid, False otherwise

Source code in src/codemap/git/commit_linter/validators.py

@staticmethod
def validate_footer_token(token: str) -> bool:
	"""
	Validate a footer token according to the Conventional Commits spec.

	According to the spec:
	1. Tokens MUST use hyphens instead of spaces
	2. BREAKING CHANGE must be uppercase
	3. Footer tokens should be ALL UPPERCASE
	4. Footer tokens should follow format with - for spaces
	5. No special characters or Unicode (non-ASCII) characters allowed

	Returns:
	    bool: True if token is valid, False otherwise

	"""
	# Check if token is a breaking change token in any case
	if BREAKING_CHANGE_REGEX.match(token.lower()):
		# If it's a breaking change token, it MUST be uppercase
		return token in (BREAKING_CHANGE, BREAKING_CHANGE_HYPHEN)

	# Check for special characters (except hyphens which are allowed)
	if any(c in token for c in "!@#$%^&*()+={}[]|\\:;\"'<>,./?"):
		return False

	# Check for non-ASCII characters
	if any(ord(c) > ASCII_MAX_VALUE for c in token):
		return False

	# Must match valid token pattern (uppercase, alphanumeric with hyphens)
	if not VALID_FOOTER_TOKEN_REGEX.match(token):
		return False

	# Check for spaces (must use hyphens instead, except for BREAKING CHANGE)
	return not (" " in token and token != BREAKING_CHANGE)

validate_type_and_scope staticmethod

validate_type_and_scope(
	type_value: str, scope_value: str | None
) -> list[str]

Validate type and scope values according to the spec.

Type must contain only letters. Scope must contain only letters, numbers, hyphens, and slashes. Both must be ASCII-only.

Parameters:

Name	Type	Description	Default
type_value	str	The commit message type	required
scope_value	str | None	The optional scope	required

Returns:

Type	Description
list[str]	list[str]: List of error messages, empty if valid

Source code in src/codemap/git/commit_linter/validators.py

@staticmethod
def validate_type_and_scope(type_value: str, scope_value: str | None) -> list[str]:
	"""
	Validate type and scope values according to the spec.

	Type must contain only letters.
	Scope must contain only letters, numbers, hyphens, and slashes.
	Both must be ASCII-only.

	Args:
	    type_value (str): The commit message type
	    scope_value (str | None): The optional scope

	Returns:
	    list[str]: List of error messages, empty if valid

	"""
	errors = []

	# Check type (no special chars or unicode)
	if not VALID_TYPE_REGEX.match(type_value):
		errors.append(f"Invalid type '{type_value}'. Types must contain only letters (a-z, A-Z).")
	elif any(ord(c) > ASCII_MAX_VALUE for c in type_value):
		errors.append(f"Invalid type '{type_value}'. Types must contain only ASCII characters.")

	# Check scope (if present)
	if scope_value is not None:
		if scope_value == "":
			errors.append("Scope cannot be empty when parentheses are used.")
		elif not VALID_SCOPE_REGEX.match(scope_value):
			errors.append(
				f"Invalid scope '{scope_value}'. Scopes must contain only letters, numbers, hyphens, and slashes."
			)
		elif any(ord(c) > ASCII_MAX_VALUE for c in scope_value):
			errors.append(f"Invalid scope '{scope_value}'. Scopes must contain only ASCII characters.")
		elif any(c in scope_value for c in "!@#$%^&*()+={}[]|\\:;\"'<>,. "):
			errors.append(f"Invalid scope '{scope_value}'. Special characters are not allowed in scopes.")

	return errors

validate_case staticmethod

validate_case(
	text: str, case_format: str | list[str]
) -> bool

Validate if the text follows the specified case format.

Parameters:

Name	Type	Description	Default
text	str	The text to validate	required
case_format	str or list	The case format(s) to check	required

Returns:

Name	Type	Description
bool	bool	True if text matches any of the specified case formats

Source code in src/codemap/git/commit_linter/validators.py

@staticmethod
def validate_case(text: str, case_format: str | list[str]) -> bool:
	"""
	Validate if the text follows the specified case format.

	Args:
	    text (str): The text to validate
	    case_format (str or list): The case format(s) to check

	Returns:
	    bool: True if text matches any of the specified case formats

	"""
	if isinstance(case_format, list):
		return any(CommitValidators.validate_case(text, fmt) for fmt in case_format)

	# Get the validator function for the specified case format
	validator = CASE_FORMATS.get(case_format)
	if not validator:
		# Default to allowing any case if invalid format specified
		return True

	return validator(text)

validate_length staticmethod

validate_length(
	text: str | None, min_length: int, max_length: float
) -> bool

Validate if text length is between min and max length.

Parameters:

Name	Type	Description	Default
text	str | None	The text to validate, or None	required
min_length	int	Minimum allowed length	required
max_length	int | float	Maximum allowed length	required

Returns:

Name	Type	Description
bool	bool	True if text length is valid, False otherwise

Source code in src/codemap/git/commit_linter/validators.py

@staticmethod
def validate_length(text: str | None, min_length: int, max_length: float) -> bool:
	"""
	Validate if text length is between min and max length.

	Args:
	    text (str | None): The text to validate, or None
	    min_length (int): Minimum allowed length
	    max_length (int | float): Maximum allowed length

	Returns:
	    bool: True if text length is valid, False otherwise

	"""
	if text is None:
		return min_length == 0

	text_length = len(text)
	return min_length <= text_length < max_length

validate_enum staticmethod

validate_enum(text: str, allowed_values: list[str]) -> bool

Validate if text is in the allowed values.

Parameters:

Name	Type	Description	Default
text	str	The text to validate	required
allowed_values	list	The allowed values	required

Returns:

Name	Type	Description
bool	bool	True if text is in allowed values, False otherwise

Source code in src/codemap/git/commit_linter/validators.py

@staticmethod
def validate_enum(text: str, allowed_values: list[str]) -> bool:
	"""
	Validate if text is in the allowed values.

	Args:
	    text (str): The text to validate
	    allowed_values (list): The allowed values

	Returns:
	    bool: True if text is in allowed values, False otherwise

	"""
	# Allow any value if no allowed values are specified
	if not allowed_values:
		return True

	return text.lower() in (value.lower() for value in allowed_values)

validate_empty staticmethod

validate_empty(
	text: str | None, should_be_empty: bool
) -> bool

Validate if text is empty or not based on configuration.

Parameters:

Name	Type	Description	Default
text	str | None	The text to validate	required
should_be_empty	bool	True if text should be empty, False if not	required

Returns:

Name	Type	Description
bool	bool	True if text empty status matches should_be_empty

Source code in src/codemap/git/commit_linter/validators.py

@staticmethod
def validate_empty(text: str | None, should_be_empty: bool) -> bool:
	"""
	Validate if text is empty or not based on configuration.

	Args:
	    text (str | None): The text to validate
	    should_be_empty (bool): True if text should be empty, False if not

	Returns:
	    bool: True if text empty status matches should_be_empty

	"""
	is_empty = text is None or text.strip() == ""
	return is_empty == should_be_empty

validate_ends_with staticmethod

validate_ends_with(
	text: str | None, suffix: str, should_end_with: bool
) -> bool

Validate if text ends with a specific suffix.

Parameters:

Name	Type	Description	Default
text	str | None	The text to validate	required
suffix	str	The suffix to check for	required
should_end_with	bool	True if text should end with suffix	required

Returns:

Name	Type	Description
bool	bool	True if text ending matches expectation

Source code in src/codemap/git/commit_linter/validators.py

@staticmethod
def validate_ends_with(text: str | None, suffix: str, should_end_with: bool) -> bool:
	"""
	Validate if text ends with a specific suffix.

	Args:
	    text (str | None): The text to validate
	    suffix (str): The suffix to check for
	    should_end_with (bool): True if text should end with suffix

	Returns:
	    bool: True if text ending matches expectation

	"""
	if text is None:
		return not should_end_with

	ends_with = text.endswith(suffix)
	return ends_with == should_end_with

validate_starts_with staticmethod

validate_starts_with(
	text: str | None, prefix: str, should_start_with: bool
) -> bool

Validate if text starts with a specific prefix.

Parameters:

Name	Type	Description	Default
text	str | None	The text to validate	required
prefix	str	The prefix to check for	required
should_start_with	bool	True if text should start with prefix	required

Returns:

Name	Type	Description
bool	bool	True if text starting matches expectation

Source code in src/codemap/git/commit_linter/validators.py

@staticmethod
def validate_starts_with(text: str | None, prefix: str, should_start_with: bool) -> bool:
	"""
	Validate if text starts with a specific prefix.

	Args:
	    text (str | None): The text to validate
	    prefix (str): The prefix to check for
	    should_start_with (bool): True if text should start with prefix

	Returns:
	    bool: True if text starting matches expectation

	"""
	if text is None:
		return not should_start_with

	starts_with = text.startswith(prefix)
	return starts_with == should_start_with

validate_line_length staticmethod

validate_line_length(
	text: str | None, max_line_length: float
) -> list[int]

Validate line lengths in multiline text.

Parameters:

Name	Type	Description	Default
text	str | None	The text to validate	required
max_line_length	int | float	Maximum allowed line length	required

Returns:

Name	Type	Description
list	list[int]	List of line numbers with errors (0-indexed)

Source code in src/codemap/git/commit_linter/validators.py

@staticmethod
def validate_line_length(text: str | None, max_line_length: float) -> list[int]:
	"""
	Validate line lengths in multiline text.

	Args:
	    text (str | None): The text to validate
	    max_line_length (int | float): Maximum allowed line length

	Returns:
	    list: List of line numbers with errors (0-indexed)

	"""
	if text is None or max_line_length == float("inf"):
		return []

	lines = text.splitlines()
	return [i for i, line in enumerate(lines) if len(line) > max_line_length]

validate_leading_blank staticmethod

validate_leading_blank(
	text: str | None, required_blank: bool
) -> bool

Validate if text starts with a blank line.

Parameters:

Name	Type	Description	Default
text	str | None	The text to validate	required
required_blank	bool	True if text should start with blank line	required

Returns:

Name	Type	Description
bool	bool	True if text leading blank matches expectation

Source code in src/codemap/git/commit_linter/validators.py

@staticmethod
def validate_leading_blank(text: str | None, required_blank: bool) -> bool:
	"""
	Validate if text starts with a blank line.

	Args:
	    text (str | None): The text to validate
	    required_blank (bool): True if text should start with blank line

	Returns:
	    bool: True if text leading blank matches expectation

	"""
	if text is None:
		return not required_blank

	lines = text.splitlines()
	has_leading_blank = len(lines) > 0 and (len(lines) == 1 or not lines[0].strip())
	return has_leading_blank == required_blank

validate_trim staticmethod

validate_trim(text: str | None) -> bool

Validate if text has no leading/trailing whitespace.

Parameters:

Name	Type	Description	Default
text	str | None	The text to validate	required

Returns:

Name	Type	Description
bool	bool	True if text has no leading/trailing whitespace

Source code in src/codemap/git/commit_linter/validators.py

@staticmethod
def validate_trim(text: str | None) -> bool:
	"""
	Validate if text has no leading/trailing whitespace.

	Args:
	    text (str | None): The text to validate

	Returns:
	    bool: True if text has no leading/trailing whitespace

	"""
	if text is None:
		return True

	return text == text.strip()

validate_contains staticmethod

validate_contains(
	text: str | None, substring: str, should_contain: bool
) -> bool

Validate if text contains a specific substring.

Parameters:

Name	Type	Description	Default
text	str | None	The text to validate	required
substring	str	The substring to check for	required
should_contain	bool	True if text should contain substring	required

Returns:

Name	Type	Description
bool	bool	True if text contains substring matches expectation

Source code in src/codemap/git/commit_linter/validators.py

@staticmethod
def validate_contains(text: str | None, substring: str, should_contain: bool) -> bool:
	"""
	Validate if text contains a specific substring.

	Args:
	    text (str | None): The text to validate
	    substring (str): The substring to check for
	    should_contain (bool): True if text should contain substring

	Returns:
	    bool: True if text contains substring matches expectation

	"""
	if text is None:
		return not should_contain

	contains = substring in text
	return contains == should_contain

semantic_grouping

Semantic grouping implementation for the CodeMap project.

This module provides functionality to group related diff chunks into semantic groups for more meaningful commit messages.

batch_generate_messages

batch_generate_messages(
	groups: list[SemanticGroup],
	prompt_template: str,
	config_loader: ConfigLoader,
	model: str | None = None,
) -> list[SemanticGroup]

Generate commit messages for multiple semantic groups in batch.

Parameters:

Name	Type	Description	Default
groups	list[SemanticGroup]	List of SemanticGroup objects	required
prompt_template	str	Template to use for prompt generation	required
config_loader	ConfigLoader	ConfigLoader instance	required
model	str | None	Optional model name override	None

Returns:

Type	Description
list[SemanticGroup]	List of SemanticGroup objects with messages added

Raises:

Type	Description
LLMError	If batch processing fails

Source code in src/codemap/git/semantic_grouping/batch_processor.py

def batch_generate_messages(
	groups: list["SemanticGroup"],
	prompt_template: str,
	config_loader: ConfigLoader,
	model: str | None = None,
) -> list["SemanticGroup"]:
	"""
	Generate commit messages for multiple semantic groups in batch.

	Args:
	    groups: List of SemanticGroup objects
	    prompt_template: Template to use for prompt generation
	    config_loader: ConfigLoader instance
	    model: Optional model name override

	Returns:
	    List of SemanticGroup objects with messages added

	Raises:
	    LLMError: If batch processing fails

	"""
	if not groups:
		return []

	# Get config values
	llm_config = config_loader.get("llm", {})
	max_tokens = llm_config.get("max_context_tokens", 4000)
	use_lod_context = llm_config.get("use_lod_context", True)
	model_name = model or llm_config.get("model", "openai/gpt-4o-mini")

	# Prepare temporary chunks and prompts for each group
	temp_chunks = []
	messages_list = []

	# Add this at the top of the function, right after getting the config values
	ui = CommitUI()

	for group in groups:
		try:
			# Create a temporary DiffChunk with optimized content if needed
			if use_lod_context and len(group.chunks) > 1:
				logger.debug("Processing semantic group with %d chunks using LOD context", len(group.chunks))
				try:
					optimized_content = process_chunks_with_lod(group.chunks, max_tokens)
					if optimized_content:
						temp_chunk = DiffChunk(files=group.files, content=optimized_content)
					else:
						temp_chunk = DiffChunk(files=group.files, content=group.content)
				except Exception:
					logger.exception("Error in LOD context processing, falling back to original content")
					temp_chunk = DiffChunk(files=group.files, content=group.content)
			else:
				temp_chunk = DiffChunk(files=group.files, content=group.content)

			# Store the temp chunk for reference
			temp_chunks.append(temp_chunk)

			# Create a simple dictionary with file paths as keys
			file_info = {file: {"path": file} for file in group.files}

			# Prepare the prompt for this group
			prompt = prepare_prompt(
				template=prompt_template,
				diff_content=temp_chunk.content,
				file_info=file_info,
				convention=config_loader.get_commit_convention(),
			)

			# Format as messages for batch_completion
			messages = [{"role": "user", "content": prompt}]
			messages_list.append(messages)

		except Exception:
			logger.exception(f"Error preparing prompt for group {group.files}")
			# Add empty messages for this group to maintain index alignment
			messages_list.append([{"role": "user", "content": "Skip this group due to error"}])

	# Use the LLM module's batch generation
	try:
		from codemap.git.commit_generator.schemas import COMMIT_MESSAGE_SCHEMA
		from codemap.llm.utils import batch_generate_completions

		# Execute batch completion using the LLM module
		responses = batch_generate_completions(
			messages_list=messages_list,
			model=model_name,
			config_loader=config_loader,
			response_format={"type": "json_object", "schema": COMMIT_MESSAGE_SCHEMA},
			temperature=llm_config.get("temperature", 0.7),
			max_tokens=llm_config.get("max_tokens", 1024),
		)

		# Process responses and update groups
		for i, (response, group) in enumerate(zip(responses, groups, strict=False)):
			try:
				# Extract content from response
				if response and hasattr(response, "choices") and response.choices:
					content = response.choices[0].message.content

					# If it's JSON, extract the message
					if content.startswith("{") and content.endswith("}"):
						try:
							# Check if it's in the {"commit_message": "..."} format
							json_data = json.loads(content)
							if "commit_message" in json_data:
								# Extract just the commit message
								content = json_data["commit_message"]
							elif "message" in json_data:
								# Extract message from {"message": "..."} format
								content = json_data["message"]
							else:
								# Use the formatter for conventional format
								content = format_commit_json(content)
						except Exception:
							logger.exception("Error formatting JSON to commit message")

					# Set the message on the group
					group.message = content
				else:
					logger.warning(f"Empty or invalid response for group {i}")
					group.message = f"update: changes to {len(group.files)} files"
			except Exception:
				logger.exception(f"Error processing response for group {i}")
				group.message = f"update: changes to {len(group.files)} files"

	except Exception:
		logger.exception("Batch completion failed")
		# Just use the already initialized UI
		ui.show_warning("LLM call failed. Using fallback commit messages.")

		# Provide fallback messages for all groups
		for group in groups:
			if not group.message:  # Don't override if already set
				fallback_msg = f"update: changes to {len(group.files)} files"
				group.message = fallback_msg
				# Log which groups received fallback messages
				logger.warning(f"Using fallback message for files: {group.files}")

	return groups

DiffClusterer

Clusters diff chunks based on their semantic embeddings.

This class provides methods to group related code changes by their semantic similarity, using vector embeddings and standard clustering algorithms from scikit-learn.

Clustering helps identify code changes that are related to each other and should be grouped in the same commit, even if they appear in different files.

The class supports multiple clustering algorithms: 1. Agglomerative clustering: Hierarchical clustering that's good for finding natural groupings without needing to specify the exact number of clusters 2. DBSCAN: Density-based clustering that can identify outliers and works well with irregularly shaped clusters

Source code in src/codemap/git/semantic_grouping/clusterer.py

class DiffClusterer:
	"""
	Clusters diff chunks based on their semantic embeddings.

	This class provides methods to group related code changes by their semantic similarity,
	using vector embeddings and standard clustering algorithms from scikit-learn.

	Clustering helps identify code changes that are related to each other and should be
	grouped in the same commit, even if they appear in different files.

	The class supports multiple clustering algorithms:
	1. Agglomerative clustering: Hierarchical clustering that's good for finding natural
	   groupings without needing to specify the exact number of clusters
	2. DBSCAN: Density-based clustering that can identify outliers and works well with
	   irregularly shaped clusters

	"""

	def __init__(self, method: str = "agglomerative", **kwargs: object) -> None:
		"""
		Initialize the clusterer.

		Args:
		    method: Clustering method to use. Options:
		        - "agglomerative": Hierarchical clustering (default)
		        - "dbscan": Density-based spatial clustering
		    **kwargs: Additional parameters for the clustering algorithm:
		        - For agglomerative: distance_threshold, linkage, etc.
		        - For DBSCAN: eps, min_samples, etc.

		Raises:
		    ImportError: If scikit-learn is not installed

		"""
		self.method = method
		self.kwargs = kwargs

		# Import here to avoid making sklearn a hard dependency
		try:
			from sklearn.cluster import DBSCAN, AgglomerativeClustering
			from sklearn.metrics.pairwise import cosine_similarity

			self.AgglomerativeClustering = AgglomerativeClustering
			self.DBSCAN = DBSCAN
			self.cosine_similarity = cosine_similarity
		except ImportError as e:
			logger.exception("Failed to import scikit-learn. Please install it with: uv add scikit-learn")
			msg = "scikit-learn is required for clustering"
			raise ImportError(msg) from e

	def cluster(self, chunk_embeddings: list[tuple[DiffChunk, np.ndarray]]) -> list[list[DiffChunk]]:
		"""
		Cluster chunks based on their embeddings.

		              Process:
		              1. Extracts chunks and embeddings from input tuples
		              2. Computes a similarity matrix using cosine similarity
		              3. Converts similarity to distance matrix (1 - similarity)
		              4. Applies clustering algorithm based on the chosen method
		              5. Organizes chunks into clusters based on labels
		              6. Handles special cases like noise points in DBSCAN

		Args:
		    chunk_embeddings: List of (chunk, embedding) tuples where each embedding
		        is a numpy array representing the semantic vector of a code chunk

		Returns:
		    List of lists, where each inner list contains chunks in the same cluster.
		    With DBSCAN, noise points (label -1) are returned as individual single-item clusters.

		Examples:
		    >>> embedder = DiffEmbedder()
		    >>> chunk_embeddings = embedder.embed_chunks(diff_chunks)
		    >>> clusterer = DiffClusterer(method="agglomerative", distance_threshold=0.5)
		    >>> clusters = clusterer.cluster(chunk_embeddings)
		    >>> for i, cluster in enumerate(clusters):
		    ...     print(f"Cluster {i} has {len(cluster)} chunks")

		"""
		if not chunk_embeddings:
			return []

		# Extract chunks and embeddings
		chunks = [ce[0] for ce in chunk_embeddings]
		embeddings = np.array([ce[1] for ce in chunk_embeddings])

		# Compute similarity matrix (1 - cosine distance)
		similarity_matrix = self.cosine_similarity(embeddings)

		# Convert to distance matrix (1 - similarity)
		distance_matrix = 1 - similarity_matrix

		# Apply clustering
		if self.method == "agglomerative":
			# Default parameters if not provided
			params = {
				"n_clusters": None,
				"distance_threshold": 0.5,  # Threshold for cluster formation (0.5 = moderate similarity)
				"metric": "precomputed",  # Use metric instead of affinity
				"linkage": "average",  # Use average linkage for balanced clusters
			}
			params.update(self.kwargs)

			clustering = self.AgglomerativeClustering(**params)
			labels = clustering.fit_predict(distance_matrix)

		elif self.method == "dbscan":
			# Default parameters if not provided
			params = {
				"eps": 0.3,  # Maximum distance between points in neighborhood (0.3 = high similarity required)
				"min_samples": 2,  # Minimum points to form a dense region
				"metric": "precomputed",  # Using precomputed distance matrix
			}
			params.update(self.kwargs)

			clustering = self.DBSCAN(**params)
			labels = clustering.fit_predict(distance_matrix)

		else:
			msg = f"Unsupported clustering method: {self.method}"
			raise ValueError(msg)

		# Group chunks by cluster label
		clusters: dict[int, list[DiffChunk]] = {}
		for i, label in enumerate(labels):
			# Convert numpy integer to Python int
			label_key = int(label)
			if label_key not in clusters:
				clusters[label_key] = []
			clusters[label_key].append(chunks[i])

		# Convert to list of lists and handle noise points (-1 label in DBSCAN)
		result: list[list[DiffChunk]] = []
		for label, cluster_chunks in sorted(clusters.items()):
			if label != -1:  # Regular cluster
				result.append(cluster_chunks)
			else:  # Noise points - each forms its own cluster
				result.extend([[chunk] for chunk in cluster_chunks])

		return result

__init__

__init__(
	method: str = "agglomerative", **kwargs: object
) -> None

Initialize the clusterer.

Parameters:

Name	Type	Description	Default
method	str	Clustering method to use. Options: - "agglomerative": Hierarchical clustering (default) - "dbscan": Density-based spatial clustering	'agglomerative'
**kwargs	object	Additional parameters for the clustering algorithm: - For agglomerative: distance_threshold, linkage, etc. - For DBSCAN: eps, min_samples, etc.	{}

Raises:

Type	Description
ImportError	If scikit-learn is not installed

Source code in src/codemap/git/semantic_grouping/clusterer.py

def __init__(self, method: str = "agglomerative", **kwargs: object) -> None:
	"""
	Initialize the clusterer.

	Args:
	    method: Clustering method to use. Options:
	        - "agglomerative": Hierarchical clustering (default)
	        - "dbscan": Density-based spatial clustering
	    **kwargs: Additional parameters for the clustering algorithm:
	        - For agglomerative: distance_threshold, linkage, etc.
	        - For DBSCAN: eps, min_samples, etc.

	Raises:
	    ImportError: If scikit-learn is not installed

	"""
	self.method = method
	self.kwargs = kwargs

	# Import here to avoid making sklearn a hard dependency
	try:
		from sklearn.cluster import DBSCAN, AgglomerativeClustering
		from sklearn.metrics.pairwise import cosine_similarity

		self.AgglomerativeClustering = AgglomerativeClustering
		self.DBSCAN = DBSCAN
		self.cosine_similarity = cosine_similarity
	except ImportError as e:
		logger.exception("Failed to import scikit-learn. Please install it with: uv add scikit-learn")
		msg = "scikit-learn is required for clustering"
		raise ImportError(msg) from e

method instance-attribute

method = method

kwargs instance-attribute

kwargs = kwargs

AgglomerativeClustering instance-attribute

AgglomerativeClustering = AgglomerativeClustering

DBSCAN instance-attribute

DBSCAN = DBSCAN

cosine_similarity instance-attribute

cosine_similarity = cosine_similarity

cluster

cluster(
	chunk_embeddings: list[tuple[DiffChunk, ndarray]],
) -> list[list[DiffChunk]]

Cluster chunks based on their embeddings.

          Process:
          1. Extracts chunks and embeddings from input tuples
          2. Computes a similarity matrix using cosine similarity
          3. Converts similarity to distance matrix (1 - similarity)
          4. Applies clustering algorithm based on the chosen method
          5. Organizes chunks into clusters based on labels
          6. Handles special cases like noise points in DBSCAN

Parameters:

Name	Type	Description	Default
chunk_embeddings	list[tuple[DiffChunk, ndarray]]	List of (chunk, embedding) tuples where each embedding is a numpy array representing the semantic vector of a code chunk	required

Returns:

Type	Description
list[list[DiffChunk]]	List of lists, where each inner list contains chunks in the same cluster.
list[list[DiffChunk]]	With DBSCAN, noise points (label -1) are returned as individual single-item clusters.

Examples:

>>> embedder = DiffEmbedder()
>>> chunk_embeddings = embedder.embed_chunks(diff_chunks)
>>> clusterer = DiffClusterer(method="agglomerative", distance_threshold=0.5)
>>> clusters = clusterer.cluster(chunk_embeddings)
>>> for i, cluster in enumerate(clusters):
...     print(f"Cluster {i} has {len(cluster)} chunks")

Source code in src/codemap/git/semantic_grouping/clusterer.py

def cluster(self, chunk_embeddings: list[tuple[DiffChunk, np.ndarray]]) -> list[list[DiffChunk]]:
	"""
	Cluster chunks based on their embeddings.

	              Process:
	              1. Extracts chunks and embeddings from input tuples
	              2. Computes a similarity matrix using cosine similarity
	              3. Converts similarity to distance matrix (1 - similarity)
	              4. Applies clustering algorithm based on the chosen method
	              5. Organizes chunks into clusters based on labels
	              6. Handles special cases like noise points in DBSCAN

	Args:
	    chunk_embeddings: List of (chunk, embedding) tuples where each embedding
	        is a numpy array representing the semantic vector of a code chunk

	Returns:
	    List of lists, where each inner list contains chunks in the same cluster.
	    With DBSCAN, noise points (label -1) are returned as individual single-item clusters.

	Examples:
	    >>> embedder = DiffEmbedder()
	    >>> chunk_embeddings = embedder.embed_chunks(diff_chunks)
	    >>> clusterer = DiffClusterer(method="agglomerative", distance_threshold=0.5)
	    >>> clusters = clusterer.cluster(chunk_embeddings)
	    >>> for i, cluster in enumerate(clusters):
	    ...     print(f"Cluster {i} has {len(cluster)} chunks")

	"""
	if not chunk_embeddings:
		return []

	# Extract chunks and embeddings
	chunks = [ce[0] for ce in chunk_embeddings]
	embeddings = np.array([ce[1] for ce in chunk_embeddings])

	# Compute similarity matrix (1 - cosine distance)
	similarity_matrix = self.cosine_similarity(embeddings)

	# Convert to distance matrix (1 - similarity)
	distance_matrix = 1 - similarity_matrix

	# Apply clustering
	if self.method == "agglomerative":
		# Default parameters if not provided
		params = {
			"n_clusters": None,
			"distance_threshold": 0.5,  # Threshold for cluster formation (0.5 = moderate similarity)
			"metric": "precomputed",  # Use metric instead of affinity
			"linkage": "average",  # Use average linkage for balanced clusters
		}
		params.update(self.kwargs)

		clustering = self.AgglomerativeClustering(**params)
		labels = clustering.fit_predict(distance_matrix)

	elif self.method == "dbscan":
		# Default parameters if not provided
		params = {
			"eps": 0.3,  # Maximum distance between points in neighborhood (0.3 = high similarity required)
			"min_samples": 2,  # Minimum points to form a dense region
			"metric": "precomputed",  # Using precomputed distance matrix
		}
		params.update(self.kwargs)

		clustering = self.DBSCAN(**params)
		labels = clustering.fit_predict(distance_matrix)

	else:
		msg = f"Unsupported clustering method: {self.method}"
		raise ValueError(msg)

	# Group chunks by cluster label
	clusters: dict[int, list[DiffChunk]] = {}
	for i, label in enumerate(labels):
		# Convert numpy integer to Python int
		label_key = int(label)
		if label_key not in clusters:
			clusters[label_key] = []
		clusters[label_key].append(chunks[i])

	# Convert to list of lists and handle noise points (-1 label in DBSCAN)
	result: list[list[DiffChunk]] = []
	for label, cluster_chunks in sorted(clusters.items()):
		if label != -1:  # Regular cluster
			result.append(cluster_chunks)
		else:  # Noise points - each forms its own cluster
			result.extend([[chunk] for chunk in cluster_chunks])

	return result

format_chunk

format_chunk(chunk: DiffChunk) -> str

Format a single diff chunk as markdown.

Parameters:

Name	Type	Description	Default
chunk	DiffChunk	The diff chunk to format	required

Returns:

Type	Description
str	Formatted markdown string

Source code in src/codemap/git/semantic_grouping/context_processor.py

def format_chunk(chunk: DiffChunk) -> str:
	"""
	Format a single diff chunk as markdown.

	Args:
	    chunk: The diff chunk to format

	Returns:
	    Formatted markdown string

	"""
	# Format file paths
	file_section = "## Files\n"
	for file in chunk.files:
		if file:
			file_section += f"- {file}\n"

	# Format content
	content_section = "### Changes\n```diff\n" + chunk.content + "\n```"

	return file_section + "\n" + content_section

prioritize_chunks

prioritize_chunks(
	chunks: list[DiffChunk], max_count: int
) -> list[DiffChunk]

Prioritize chunks based on heuristics (file types, changes, etc.).

This is a simple implementation that could be extended with more sophisticated dissimilarity metrics.

Parameters:

Name	Type	Description	Default
chunks	list[DiffChunk]	List of chunks to prioritize	required
max_count	int	Maximum number of chunks to return	required

Returns:

Type	Description
list[DiffChunk]	Prioritized list of chunks

Source code in src/codemap/git/semantic_grouping/context_processor.py

def prioritize_chunks(chunks: list[DiffChunk], max_count: int) -> list[DiffChunk]:
	"""
	Prioritize chunks based on heuristics (file types, changes, etc.).

	This is a simple implementation that could be extended with more
	sophisticated dissimilarity metrics.

	Args:
	    chunks: List of chunks to prioritize
	    max_count: Maximum number of chunks to return

	Returns:
	    Prioritized list of chunks

	"""
	# Simple heuristics for now:
	# 1. Prefer chunks with code files over non-code files
	# 2. Prefer chunks with more files (more central changes)
	# 3. Prefer chunks with more added/changed lines

	def chunk_score(chunk: DiffChunk) -> float:
		"""Calculates a priority score for a diff chunk based on heuristics.

		The score is calculated using three factors:
		1. Presence of code files (60% weight)
		2. Number of files affected (20% weight)
		3. Size of content changes (20% weight)

		Args:
			chunk: The diff chunk to score

		Returns:
			float: A score between 0 and 1 representing the chunk's priority
		"""
		# Check if any files are code files
		code_file_score = 0
		for file in chunk.files:
			if any(file.endswith(ext) for ext in [".py", ".js", ".ts", ".java", ".c", ".cpp", ".go"]):
				code_file_score = 1
				break

		# Score based on number of files
		file_count_score = min(len(chunk.files), 3) / 3

		# Score based on content size (as proxy for changes)
		content_score = min(len(chunk.content), 1000) / 1000

		return code_file_score * 0.6 + file_count_score * 0.2 + content_score * 0.2

	# Sort chunks by score and return top max_count
	return sorted(chunks, key=chunk_score, reverse=True)[:max_count]

process_chunks_with_lod

process_chunks_with_lod(
	chunks: list[DiffChunk],
	max_tokens: int = DEFAULT_MAX_TOKENS,
) -> str

Process diff chunks using LOD to create optimized context for LLM prompts.

Parameters:

Name	Type	Description	Default
chunks	list[DiffChunk]	List of diff chunks to process	required
max_tokens	int	Maximum tokens allowed in the formatted context	DEFAULT_MAX_TOKENS

Returns:

Type	Description
str	Formatted markdown context optimized for token usage

Source code in src/codemap/git/semantic_grouping/context_processor.py

def process_chunks_with_lod(chunks: list[DiffChunk], max_tokens: int = DEFAULT_MAX_TOKENS) -> str:
	"""
	Process diff chunks using LOD to create optimized context for LLM prompts.

	Args:
	    chunks: List of diff chunks to process
	    max_tokens: Maximum tokens allowed in the formatted context

	Returns:
	    Formatted markdown context optimized for token usage

	"""
	# If chunks list is small, we might not need LOD processing
	if len(chunks) <= MAX_SIMPLE_CHUNKS:
		return format_regular_chunks(chunks[:MAX_CHUNKS])

	# Set up LOD generator and estimate number of chunks we can include
	lod_generator = LODGenerator()
	estimated_chunk_count = min(max_tokens // CHUNK_TOKEN_ESTIMATE, len(chunks))
	prioritized_chunks = prioritize_chunks(chunks, min(estimated_chunk_count, MAX_CHUNKS))

	# Start with highest LOD level and progressively reduce if needed
	lod_levels = [LODLevel.STRUCTURE, LODLevel.SIGNATURES]
	formatted_chunks = []
	current_level_index = 0

	while current_level_index < len(lod_levels):
		current_level = lod_levels[current_level_index]
		formatted_chunks = []

		for chunk in prioritized_chunks:
			# Get file paths from chunk
			file_paths = get_file_paths_from_chunk(chunk)

			if not file_paths:
				# If we can't extract paths, use regular formatting for this chunk
				formatted_chunks.append(format_chunk(chunk))
				continue

			# Process each file in the chunk with LOD
			lod_formatted = []
			for file_path in file_paths:
				path = Path(file_path)
				if not path.exists():
					continue

				# Generate LOD representation
				lod_entity = lod_generator.generate_lod(path, level=current_level)
				if lod_entity:
					lod_formatted.append(format_lod_entity(lod_entity, file_path, current_level))

			if lod_formatted:
				formatted_chunks.append("\n".join(lod_formatted))
			else:
				# Fallback to regular formatting
				formatted_chunks.append(format_chunk(chunk))

		# Estimate if we're within token limit
		total_context = "\n\n".join(formatted_chunks)
		estimated_tokens = estimate_tokens(total_context)

		if estimated_tokens <= max_tokens or current_level_index == len(lod_levels) - 1:
			break

		# Try with lower LOD level
		current_level_index += 1

	# If we still exceed the token limit, truncate
	total_context = "\n\n".join(formatted_chunks)
	if estimate_tokens(total_context) > max_tokens:
		total_context = truncate_context(total_context, max_tokens)

	return total_context

DiffEmbedder

Generates embeddings for diff chunks.

Source code in src/codemap/git/semantic_grouping/embedder.py

class DiffEmbedder:
	"""Generates embeddings for diff chunks."""

	def __init__(self, model_name: str = "all-MiniLM-L6-v2") -> None:
		"""
		Initialize the embedder with a specific model.

		Args:
		    model_name: Name of the sentence-transformers model to use

		"""
		# Import here to avoid making sentence-transformers a hard dependency
		try:
			from sentence_transformers import SentenceTransformer

			self.model = SentenceTransformer(model_name)
		except ImportError as e:
			logger.exception(
				"Failed to import sentence-transformers. Please install it with: uv add sentence-transformers"
			)
			msg = "sentence-transformers is required for semantic grouping"
			raise ImportError(msg) from e

	def preprocess_diff(self, diff_text: str) -> str:
		"""
		Preprocess diff text to make it more suitable for embedding.

		Args:
		    diff_text: Raw diff text

		Returns:
		    Preprocessed text

		"""
		# Remove diff headers, line numbers, etc.
		# Focus on actual content changes
		lines = []
		for line in diff_text.splitlines():
			# Skip diff metadata lines
			if line.startswith(("diff --git", "index ", "+++", "---")):
				continue

			# Keep actual content changes, removing the +/- prefix
			if line.startswith(("+", "-", " ")):
				lines.append(line[1:])

		return "\n".join(lines)

	def embed_chunk(self, chunk: DiffChunk) -> np.ndarray:
		"""
		Generate an embedding for a diff chunk.

		Args:
		    chunk: DiffChunk object

		Returns:
		    numpy.ndarray: Embedding vector

		"""
		# Get the diff content from the chunk
		diff_text = chunk.content

		# Preprocess the diff text
		processed_text = self.preprocess_diff(diff_text)

		# If the processed text is empty, use the file paths as context
		if not processed_text.strip():
			processed_text = " ".join(chunk.files)

		# Generate the embedding and convert to numpy array
		embedding = self.model.encode(processed_text)
		return np.array(embedding)

	def embed_chunks(self, chunks: list[DiffChunk]) -> list[tuple[DiffChunk, np.ndarray]]:
		"""
		Generate embeddings for multiple chunks.

		Args:
		    chunks: List of DiffChunk objects

		Returns:
		    List of (chunk, embedding) tuples

		"""
		return [(chunk, self.embed_chunk(chunk)) for chunk in chunks]

__init__

__init__(model_name: str = 'all-MiniLM-L6-v2') -> None

Initialize the embedder with a specific model.

Parameters:

Name	Type	Description	Default
model_name	str	Name of the sentence-transformers model to use	'all-MiniLM-L6-v2'

Source code in src/codemap/git/semantic_grouping/embedder.py

def __init__(self, model_name: str = "all-MiniLM-L6-v2") -> None:
	"""
	Initialize the embedder with a specific model.

	Args:
	    model_name: Name of the sentence-transformers model to use

	"""
	# Import here to avoid making sentence-transformers a hard dependency
	try:
		from sentence_transformers import SentenceTransformer

		self.model = SentenceTransformer(model_name)
	except ImportError as e:
		logger.exception(
			"Failed to import sentence-transformers. Please install it with: uv add sentence-transformers"
		)
		msg = "sentence-transformers is required for semantic grouping"
		raise ImportError(msg) from e

model instance-attribute

model = SentenceTransformer(model_name)

preprocess_diff

preprocess_diff(diff_text: str) -> str

Preprocess diff text to make it more suitable for embedding.

Parameters:

Name	Type	Description	Default
diff_text	str	Raw diff text	required

Returns:

Type	Description
str	Preprocessed text

Source code in src/codemap/git/semantic_grouping/embedder.py

def preprocess_diff(self, diff_text: str) -> str:
	"""
	Preprocess diff text to make it more suitable for embedding.

	Args:
	    diff_text: Raw diff text

	Returns:
	    Preprocessed text

	"""
	# Remove diff headers, line numbers, etc.
	# Focus on actual content changes
	lines = []
	for line in diff_text.splitlines():
		# Skip diff metadata lines
		if line.startswith(("diff --git", "index ", "+++", "---")):
			continue

		# Keep actual content changes, removing the +/- prefix
		if line.startswith(("+", "-", " ")):
			lines.append(line[1:])

	return "\n".join(lines)

embed_chunk

embed_chunk(chunk: DiffChunk) -> ndarray

Generate an embedding for a diff chunk.

Parameters:

Name	Type	Description	Default
chunk	DiffChunk	DiffChunk object	required

Returns:

Type	Description
ndarray	numpy.ndarray: Embedding vector

Source code in src/codemap/git/semantic_grouping/embedder.py

def embed_chunk(self, chunk: DiffChunk) -> np.ndarray:
	"""
	Generate an embedding for a diff chunk.

	Args:
	    chunk: DiffChunk object

	Returns:
	    numpy.ndarray: Embedding vector

	"""
	# Get the diff content from the chunk
	diff_text = chunk.content

	# Preprocess the diff text
	processed_text = self.preprocess_diff(diff_text)

	# If the processed text is empty, use the file paths as context
	if not processed_text.strip():
		processed_text = " ".join(chunk.files)

	# Generate the embedding and convert to numpy array
	embedding = self.model.encode(processed_text)
	return np.array(embedding)

embed_chunks

embed_chunks(
	chunks: list[DiffChunk],
) -> list[tuple[DiffChunk, ndarray]]

Generate embeddings for multiple chunks.

Parameters:

Name	Type	Description	Default
chunks	list[DiffChunk]	List of DiffChunk objects	required

Returns:

Type	Description
list[tuple[DiffChunk, ndarray]]	List of (chunk, embedding) tuples

Source code in src/codemap/git/semantic_grouping/embedder.py

def embed_chunks(self, chunks: list[DiffChunk]) -> list[tuple[DiffChunk, np.ndarray]]:
	"""
	Generate embeddings for multiple chunks.

	Args:
	    chunks: List of DiffChunk objects

	Returns:
	    List of (chunk, embedding) tuples

	"""
	return [(chunk, self.embed_chunk(chunk)) for chunk in chunks]

FileIntegrityResolver

Resolves file integrity constraints for semantic groups.

File integrity refers to the requirement that all changes to a specific file should be included in the same commit, even if they are semantically different. This prevents fragmented changes to the same file across multiple commits, which can lead to broken builds or inconsistent states.

The resolver works by: 1. Identifying files that appear in multiple semantic groups 2. Calculating the semantic similarity between these overlapping groups 3. Either merging similar groups or reassigning chunks from less relevant groups to the most appropriate group

This process ensures that each file is modified in exactly one commit, while still maintaining semantic coherence within commits when possible.

Source code in src/codemap/git/semantic_grouping/resolver.py

class FileIntegrityResolver:
	"""
	Resolves file integrity constraints for semantic groups.

	File integrity refers to the requirement that all changes to a specific file should
	be included in the same commit, even if they are semantically different. This prevents
	fragmented changes to the same file across multiple commits, which can lead to broken builds
	or inconsistent states.

	The resolver works by:
	1. Identifying files that appear in multiple semantic groups
	2. Calculating the semantic similarity between these overlapping groups
	3. Either merging similar groups or reassigning chunks from less relevant groups
	   to the most appropriate group

	This process ensures that each file is modified in exactly one commit, while still
	maintaining semantic coherence within commits when possible.

	"""

	def __init__(self, similarity_threshold: float = 0.6) -> None:
		"""
		Initialize the resolver.

		Args:
		    similarity_threshold: Threshold for group similarity to trigger merging (0.0-1.0).
		        Higher values require greater similarity to merge groups:
		        - Values near 0.5 are permissive and will merge moderately related groups
		        - Values above 0.7 are strict and will mostly reassign chunks instead of merging
		        - Default 0.6 provides a balanced approach

		Raises:
		    ImportError: If scikit-learn is not installed

		"""
		self.similarity_threshold = similarity_threshold

		# Import here to avoid making sklearn a hard dependency
		try:
			from sklearn.metrics.pairwise import cosine_similarity

			self.cosine_similarity = cosine_similarity
		except ImportError as e:
			logger.exception("Failed to import scikit-learn. Please install it with: uv add scikit-learn")
			msg = "scikit-learn is required for file integrity resolution"
			raise ImportError(msg) from e

	def calculate_group_similarity(
		self, group1: "SemanticGroup", group2: "SemanticGroup", chunk_embeddings: dict[DiffChunk, np.ndarray]
	) -> float:
		"""
		Calculate similarity between two groups based on their chunks' embeddings.

		This method computes the average pairwise cosine similarity between all combinations
		of chunks from the two groups. The similarity is based on the semantic embeddings
		of the chunks' content.

		Process:
		1. Extract embeddings for all chunks in both groups
		2. Compute pairwise cosine similarities between each pair of chunks
		3. Return the average similarity score

		Args:
		    group1: First semantic group to compare
		    group2: Second semantic group to compare
		    chunk_embeddings: Dict mapping chunks to their embeddings

		Returns:
		    float: Similarity score between 0 and 1, where:
		        - 0 indicates completely unrelated changes
		        - 1 indicates identical or extremely similar changes
		        - Values around 0.6-0.8 typically indicate related functionality

		"""
		# Get embeddings for chunks in each group
		embeddings1 = [chunk_embeddings[chunk] for chunk in group1.chunks if chunk in chunk_embeddings]
		embeddings2 = [chunk_embeddings[chunk] for chunk in group2.chunks if chunk in chunk_embeddings]

		if not embeddings1 or not embeddings2:
			return 0.0

		# Calculate pairwise similarities
		similarities = []
		for emb1 in embeddings1:
			for emb2 in embeddings2:
				sim = self.cosine_similarity([emb1], [emb2])[0][0]
				similarities.append(sim)

		# Return average similarity
		return sum(similarities) / len(similarities) if similarities else 0.0

	def resolve_violations(
		self, groups: list["SemanticGroup"], chunk_embeddings: dict[DiffChunk, np.ndarray]
	) -> list["SemanticGroup"]:
		"""
		Resolve file integrity violations by merging or reassigning chunks.

		A violation occurs when the same file appears in multiple semantic groups.
		This needs to be resolved because a file should be modified in only one commit.

		Args:
		    groups: List of SemanticGroup objects to resolve
		    chunk_embeddings: Dict mapping chunks to their embeddings

		Returns:
		    List of SemanticGroup objects with all violations resolved

		"""
		# Keep iterating until no violations remain
		while True:
			# Build file to groups mapping
			file_to_groups: dict[str, list[int]] = {}
			for i, group in enumerate(groups):
				for file in group.files:
					if file not in file_to_groups:
						file_to_groups[file] = []
					file_to_groups[file].append(i)

			# Find violations (files in multiple groups)
			violations = {file: indices for file, indices in file_to_groups.items() if len(indices) > 1}

			if not violations:
				break  # No violations, we're done

			# Process the first violation
			file = next(iter(violations))
			group_indices = violations[file]

			# Try to find groups to merge based on similarity
			max_similarity = 0
			groups_to_merge = None

			# Calculate similarities between all pairs of groups containing this file
			for i in range(len(group_indices)):
				for j in range(i + 1, len(group_indices)):
					idx1, idx2 = group_indices[i], group_indices[j]
					similarity = self.calculate_group_similarity(groups[idx1], groups[idx2], chunk_embeddings)

					if similarity > max_similarity:
						max_similarity = similarity
						groups_to_merge = (idx1, idx2)

			# Decide whether to merge or reassign based on similarity threshold
			if max_similarity >= self.similarity_threshold and groups_to_merge:
				# STRATEGY 1: Merge groups if they're similar enough
				idx1, idx2 = groups_to_merge
				merged_group = groups[idx1].merge_with(groups[idx2])

				# Replace the first group with the merged one and remove the second
				groups[idx1] = merged_group
				groups.pop(idx2)
			else:
				# STRATEGY 2: Reassign chunks to the primary group for this file
				# Find the primary group (group with most chunks containing this file)
				file_chunks_count = []
				for idx in group_indices:
					count = sum(1 for chunk in groups[idx].chunks if file in chunk.files)
					file_chunks_count.append((idx, count))

				# Sort by count descending
				file_chunks_count.sort(key=lambda x: x[1], reverse=True)
				primary_idx = file_chunks_count[0][0]

				# Move chunks containing this file to the primary group
				for idx in group_indices:
					if idx != primary_idx:
						# Find chunks containing this file
						chunks_to_move = [chunk for chunk in groups[idx].chunks if file in chunk.files]

						# Move chunks to primary group
						groups[primary_idx].chunks.extend(chunks_to_move)

						# Remove moved chunks from original group
						groups[idx].chunks = [chunk for chunk in groups[idx].chunks if file not in chunk.files]

				# Remove empty groups
				groups = [group for group in groups if group.chunks]

		return groups

__init__

__init__(similarity_threshold: float = 0.6) -> None

Initialize the resolver.

Parameters:

Name	Type	Description	Default
similarity_threshold	float	Threshold for group similarity to trigger merging (0.0-1.0). Higher values require greater similarity to merge groups: - Values near 0.5 are permissive and will merge moderately related groups - Values above 0.7 are strict and will mostly reassign chunks instead of merging - Default 0.6 provides a balanced approach	0.6

Raises:

Type	Description
ImportError	If scikit-learn is not installed

Source code in src/codemap/git/semantic_grouping/resolver.py

def __init__(self, similarity_threshold: float = 0.6) -> None:
	"""
	Initialize the resolver.

	Args:
	    similarity_threshold: Threshold for group similarity to trigger merging (0.0-1.0).
	        Higher values require greater similarity to merge groups:
	        - Values near 0.5 are permissive and will merge moderately related groups
	        - Values above 0.7 are strict and will mostly reassign chunks instead of merging
	        - Default 0.6 provides a balanced approach

	Raises:
	    ImportError: If scikit-learn is not installed

	"""
	self.similarity_threshold = similarity_threshold

	# Import here to avoid making sklearn a hard dependency
	try:
		from sklearn.metrics.pairwise import cosine_similarity

		self.cosine_similarity = cosine_similarity
	except ImportError as e:
		logger.exception("Failed to import scikit-learn. Please install it with: uv add scikit-learn")
		msg = "scikit-learn is required for file integrity resolution"
		raise ImportError(msg) from e

similarity_threshold instance-attribute

similarity_threshold = similarity_threshold

cosine_similarity instance-attribute

cosine_similarity = cosine_similarity

calculate_group_similarity

calculate_group_similarity(
	group1: SemanticGroup,
	group2: SemanticGroup,
	chunk_embeddings: dict[DiffChunk, ndarray],
) -> float

Calculate similarity between two groups based on their chunks' embeddings.

This method computes the average pairwise cosine similarity between all combinations of chunks from the two groups. The similarity is based on the semantic embeddings of the chunks' content.

Process: 1. Extract embeddings for all chunks in both groups 2. Compute pairwise cosine similarities between each pair of chunks 3. Return the average similarity score

Parameters:

Name	Type	Description	Default
group1	SemanticGroup	First semantic group to compare	required
group2	SemanticGroup	Second semantic group to compare	required
chunk_embeddings	dict[DiffChunk, ndarray]	Dict mapping chunks to their embeddings	required

Returns:

Name	Type	Description
float	float	Similarity score between 0 and 1, where: - 0 indicates completely unrelated changes - 1 indicates identical or extremely similar changes - Values around 0.6-0.8 typically indicate related functionality

Source code in src/codemap/git/semantic_grouping/resolver.py

def calculate_group_similarity(
	self, group1: "SemanticGroup", group2: "SemanticGroup", chunk_embeddings: dict[DiffChunk, np.ndarray]
) -> float:
	"""
	Calculate similarity between two groups based on their chunks' embeddings.

	This method computes the average pairwise cosine similarity between all combinations
	of chunks from the two groups. The similarity is based on the semantic embeddings
	of the chunks' content.

	Process:
	1. Extract embeddings for all chunks in both groups
	2. Compute pairwise cosine similarities between each pair of chunks
	3. Return the average similarity score

	Args:
	    group1: First semantic group to compare
	    group2: Second semantic group to compare
	    chunk_embeddings: Dict mapping chunks to their embeddings

	Returns:
	    float: Similarity score between 0 and 1, where:
	        - 0 indicates completely unrelated changes
	        - 1 indicates identical or extremely similar changes
	        - Values around 0.6-0.8 typically indicate related functionality

	"""
	# Get embeddings for chunks in each group
	embeddings1 = [chunk_embeddings[chunk] for chunk in group1.chunks if chunk in chunk_embeddings]
	embeddings2 = [chunk_embeddings[chunk] for chunk in group2.chunks if chunk in chunk_embeddings]

	if not embeddings1 or not embeddings2:
		return 0.0

	# Calculate pairwise similarities
	similarities = []
	for emb1 in embeddings1:
		for emb2 in embeddings2:
			sim = self.cosine_similarity([emb1], [emb2])[0][0]
			similarities.append(sim)

	# Return average similarity
	return sum(similarities) / len(similarities) if similarities else 0.0

resolve_violations

resolve_violations(
	groups: list[SemanticGroup],
	chunk_embeddings: dict[DiffChunk, ndarray],
) -> list[SemanticGroup]

Resolve file integrity violations by merging or reassigning chunks.

A violation occurs when the same file appears in multiple semantic groups. This needs to be resolved because a file should be modified in only one commit.

Parameters:

Name	Type	Description	Default
groups	list[SemanticGroup]	List of SemanticGroup objects to resolve	required
chunk_embeddings	dict[DiffChunk, ndarray]	Dict mapping chunks to their embeddings	required

Returns:

Type	Description
list[SemanticGroup]	List of SemanticGroup objects with all violations resolved

Source code in src/codemap/git/semantic_grouping/resolver.py

def resolve_violations(
	self, groups: list["SemanticGroup"], chunk_embeddings: dict[DiffChunk, np.ndarray]
) -> list["SemanticGroup"]:
	"""
	Resolve file integrity violations by merging or reassigning chunks.

	A violation occurs when the same file appears in multiple semantic groups.
	This needs to be resolved because a file should be modified in only one commit.

	Args:
	    groups: List of SemanticGroup objects to resolve
	    chunk_embeddings: Dict mapping chunks to their embeddings

	Returns:
	    List of SemanticGroup objects with all violations resolved

	"""
	# Keep iterating until no violations remain
	while True:
		# Build file to groups mapping
		file_to_groups: dict[str, list[int]] = {}
		for i, group in enumerate(groups):
			for file in group.files:
				if file not in file_to_groups:
					file_to_groups[file] = []
				file_to_groups[file].append(i)

		# Find violations (files in multiple groups)
		violations = {file: indices for file, indices in file_to_groups.items() if len(indices) > 1}

		if not violations:
			break  # No violations, we're done

		# Process the first violation
		file = next(iter(violations))
		group_indices = violations[file]

		# Try to find groups to merge based on similarity
		max_similarity = 0
		groups_to_merge = None

		# Calculate similarities between all pairs of groups containing this file
		for i in range(len(group_indices)):
			for j in range(i + 1, len(group_indices)):
				idx1, idx2 = group_indices[i], group_indices[j]
				similarity = self.calculate_group_similarity(groups[idx1], groups[idx2], chunk_embeddings)

				if similarity > max_similarity:
					max_similarity = similarity
					groups_to_merge = (idx1, idx2)

		# Decide whether to merge or reassign based on similarity threshold
		if max_similarity >= self.similarity_threshold and groups_to_merge:
			# STRATEGY 1: Merge groups if they're similar enough
			idx1, idx2 = groups_to_merge
			merged_group = groups[idx1].merge_with(groups[idx2])

			# Replace the first group with the merged one and remove the second
			groups[idx1] = merged_group
			groups.pop(idx2)
		else:
			# STRATEGY 2: Reassign chunks to the primary group for this file
			# Find the primary group (group with most chunks containing this file)
			file_chunks_count = []
			for idx in group_indices:
				count = sum(1 for chunk in groups[idx].chunks if file in chunk.files)
				file_chunks_count.append((idx, count))

			# Sort by count descending
			file_chunks_count.sort(key=lambda x: x[1], reverse=True)
			primary_idx = file_chunks_count[0][0]

			# Move chunks containing this file to the primary group
			for idx in group_indices:
				if idx != primary_idx:
					# Find chunks containing this file
					chunks_to_move = [chunk for chunk in groups[idx].chunks if file in chunk.files]

					# Move chunks to primary group
					groups[primary_idx].chunks.extend(chunks_to_move)

					# Remove moved chunks from original group
					groups[idx].chunks = [chunk for chunk in groups[idx].chunks if file not in chunk.files]

			# Remove empty groups
			groups = [group for group in groups if group.chunks]

	return groups

SemanticGroup dataclass

A semantic group of related diff chunks.

This class represents a group of related diff chunks that should be committed together because they are semantically related.

Source code in src/codemap/git/semantic_grouping/__init__.py

@dataclass
class SemanticGroup:
	"""
	A semantic group of related diff chunks.

	This class represents a group of related diff chunks that should be
	committed together because they are semantically related.

	"""

	chunks: list[DiffChunk] = field(default_factory=list)
	files: list[str] = field(default_factory=list)
	content: str = ""
	message: str | None = None
	approved: bool = False
	embedding: list[float] | None = None

	def __post_init__(self) -> None:
		"""Initialize files and content from chunks if not provided."""
		if not self.files and self.chunks:
			# Extract all unique files from chunks
			all_files = []
			for chunk in self.chunks:
				all_files.extend(chunk.files)
			self.files = sorted(set(all_files))

		if not self.content and self.chunks:
			# Combine content from all chunks
			self.content = "\n\n".join(chunk.content for chunk in self.chunks if chunk.content)

	def merge_with(self, other: "SemanticGroup") -> "SemanticGroup":
		"""
		Merge this group with another group.

		Args:
		        other: Another SemanticGroup to merge with

		Returns:
		        A new SemanticGroup containing chunks from both groups

		"""
		# Combine chunks from both groups
		combined_chunks = list(self.chunks)
		combined_chunks.extend(other.chunks)

		# Create a new group with the combined chunks
		result = SemanticGroup(chunks=combined_chunks)

		# If both groups have a message, prefer the one from self
		if self.message:
			result.message = self.message
		elif other.message:
			result.message = other.message

		return result

__init__

__init__(
	chunks: list[DiffChunk] = list(),
	files: list[str] = list(),
	content: str = "",
	message: str | None = None,
	approved: bool = False,
	embedding: list[float] | None = None,
) -> None

chunks class-attribute instance-attribute

chunks: list[DiffChunk] = field(default_factory=list)

files class-attribute instance-attribute

files: list[str] = field(default_factory=list)

content class-attribute instance-attribute

content: str = ''

message class-attribute instance-attribute

message: str | None = None

approved class-attribute instance-attribute

approved: bool = False

embedding class-attribute instance-attribute

embedding: list[float] | None = None

__post_init__

__post_init__() -> None

Initialize files and content from chunks if not provided.

Source code in src/codemap/git/semantic_grouping/__init__.py

def __post_init__(self) -> None:
	"""Initialize files and content from chunks if not provided."""
	if not self.files and self.chunks:
		# Extract all unique files from chunks
		all_files = []
		for chunk in self.chunks:
			all_files.extend(chunk.files)
		self.files = sorted(set(all_files))

	if not self.content and self.chunks:
		# Combine content from all chunks
		self.content = "\n\n".join(chunk.content for chunk in self.chunks if chunk.content)

merge_with

merge_with(other: SemanticGroup) -> SemanticGroup

Merge this group with another group.

Parameters:

Name	Type	Description	Default
other	SemanticGroup	Another SemanticGroup to merge with	required

Returns:

Type	Description
SemanticGroup	A new SemanticGroup containing chunks from both groups

Source code in src/codemap/git/semantic_grouping/__init__.py

def merge_with(self, other: "SemanticGroup") -> "SemanticGroup":
	"""
	Merge this group with another group.

	Args:
	        other: Another SemanticGroup to merge with

	Returns:
	        A new SemanticGroup containing chunks from both groups

	"""
	# Combine chunks from both groups
	combined_chunks = list(self.chunks)
	combined_chunks.extend(other.chunks)

	# Create a new group with the combined chunks
	result = SemanticGroup(chunks=combined_chunks)

	# If both groups have a message, prefer the one from self
	if self.message:
		result.message = self.message
	elif other.message:
		result.message = other.message

	return result

batch_processor

Batch processing for semantic groups commit message generation.

This module provides functionality to generate commit messages for multiple semantic groups in batch using LiteLLM's batch_completion.

logger module-attribute

logger = getLogger(__name__)

batch_generate_messages

batch_generate_messages(
	groups: list[SemanticGroup],
	prompt_template: str,
	config_loader: ConfigLoader,
	model: str | None = None,
) -> list[SemanticGroup]

Generate commit messages for multiple semantic groups in batch.

Parameters:

Name	Type	Description	Default
groups	list[SemanticGroup]	List of SemanticGroup objects	required
prompt_template	str	Template to use for prompt generation	required
config_loader	ConfigLoader	ConfigLoader instance	required
model	str | None	Optional model name override	None

Returns:

Type	Description
list[SemanticGroup]	List of SemanticGroup objects with messages added

Raises:

Type	Description
LLMError	If batch processing fails

Source code in src/codemap/git/semantic_grouping/batch_processor.py

def batch_generate_messages(
	groups: list["SemanticGroup"],
	prompt_template: str,
	config_loader: ConfigLoader,
	model: str | None = None,
) -> list["SemanticGroup"]:
	"""
	Generate commit messages for multiple semantic groups in batch.

	Args:
	    groups: List of SemanticGroup objects
	    prompt_template: Template to use for prompt generation
	    config_loader: ConfigLoader instance
	    model: Optional model name override

	Returns:
	    List of SemanticGroup objects with messages added

	Raises:
	    LLMError: If batch processing fails

	"""
	if not groups:
		return []

	# Get config values
	llm_config = config_loader.get("llm", {})
	max_tokens = llm_config.get("max_context_tokens", 4000)
	use_lod_context = llm_config.get("use_lod_context", True)
	model_name = model or llm_config.get("model", "openai/gpt-4o-mini")

	# Prepare temporary chunks and prompts for each group
	temp_chunks = []
	messages_list = []

	# Add this at the top of the function, right after getting the config values
	ui = CommitUI()

	for group in groups:
		try:
			# Create a temporary DiffChunk with optimized content if needed
			if use_lod_context and len(group.chunks) > 1:
				logger.debug("Processing semantic group with %d chunks using LOD context", len(group.chunks))
				try:
					optimized_content = process_chunks_with_lod(group.chunks, max_tokens)
					if optimized_content:
						temp_chunk = DiffChunk(files=group.files, content=optimized_content)
					else:
						temp_chunk = DiffChunk(files=group.files, content=group.content)
				except Exception:
					logger.exception("Error in LOD context processing, falling back to original content")
					temp_chunk = DiffChunk(files=group.files, content=group.content)
			else:
				temp_chunk = DiffChunk(files=group.files, content=group.content)

			# Store the temp chunk for reference
			temp_chunks.append(temp_chunk)

			# Create a simple dictionary with file paths as keys
			file_info = {file: {"path": file} for file in group.files}

			# Prepare the prompt for this group
			prompt = prepare_prompt(
				template=prompt_template,
				diff_content=temp_chunk.content,
				file_info=file_info,
				convention=config_loader.get_commit_convention(),
			)

			# Format as messages for batch_completion
			messages = [{"role": "user", "content": prompt}]
			messages_list.append(messages)

		except Exception:
			logger.exception(f"Error preparing prompt for group {group.files}")
			# Add empty messages for this group to maintain index alignment
			messages_list.append([{"role": "user", "content": "Skip this group due to error"}])

	# Use the LLM module's batch generation
	try:
		from codemap.git.commit_generator.schemas import COMMIT_MESSAGE_SCHEMA
		from codemap.llm.utils import batch_generate_completions

		# Execute batch completion using the LLM module
		responses = batch_generate_completions(
			messages_list=messages_list,
			model=model_name,
			config_loader=config_loader,
			response_format={"type": "json_object", "schema": COMMIT_MESSAGE_SCHEMA},
			temperature=llm_config.get("temperature", 0.7),
			max_tokens=llm_config.get("max_tokens", 1024),
		)

		# Process responses and update groups
		for i, (response, group) in enumerate(zip(responses, groups, strict=False)):
			try:
				# Extract content from response
				if response and hasattr(response, "choices") and response.choices:
					content = response.choices[0].message.content

					# If it's JSON, extract the message
					if content.startswith("{") and content.endswith("}"):
						try:
							# Check if it's in the {"commit_message": "..."} format
							json_data = json.loads(content)
							if "commit_message" in json_data:
								# Extract just the commit message
								content = json_data["commit_message"]
							elif "message" in json_data:
								# Extract message from {"message": "..."} format
								content = json_data["message"]
							else:
								# Use the formatter for conventional format
								content = format_commit_json(content)
						except Exception:
							logger.exception("Error formatting JSON to commit message")

					# Set the message on the group
					group.message = content
				else:
					logger.warning(f"Empty or invalid response for group {i}")
					group.message = f"update: changes to {len(group.files)} files"
			except Exception:
				logger.exception(f"Error processing response for group {i}")
				group.message = f"update: changes to {len(group.files)} files"

	except Exception:
		logger.exception("Batch completion failed")
		# Just use the already initialized UI
		ui.show_warning("LLM call failed. Using fallback commit messages.")

		# Provide fallback messages for all groups
		for group in groups:
			if not group.message:  # Don't override if already set
				fallback_msg = f"update: changes to {len(group.files)} files"
				group.message = fallback_msg
				# Log which groups received fallback messages
				logger.warning(f"Using fallback message for files: {group.files}")

	return groups

resolver

Module for resolving file integrity constraints in semantic groups.

This module provides functionality for ensuring that changes to the same file are kept in the same commit, even when semantic clustering might separate them. This ensures that file integrity is maintained during the commit process.

Key components: - FileIntegrityResolver: Main class that analyzes file overlaps between semantic groups and decides whether to merge groups or reassign chunks to maintain file integrity

The resolution process involves: 1. Detecting violations (files that appear in multiple semantic groups) 2. Calculating semantic similarity between groups with overlapping files 3. Deciding whether to merge groups (if sufficiently similar) or reassign chunks 4. Iteratively resolving violations until all files are in exactly one group

logger module-attribute

logger = getLogger(__name__)

T module-attribute

T = TypeVar('T', bound=DiffChunk)

FileIntegrityResolver

Resolves file integrity constraints for semantic groups.

File integrity refers to the requirement that all changes to a specific file should be included in the same commit, even if they are semantically different. This prevents fragmented changes to the same file across multiple commits, which can lead to broken builds or inconsistent states.

The resolver works by: 1. Identifying files that appear in multiple semantic groups 2. Calculating the semantic similarity between these overlapping groups 3. Either merging similar groups or reassigning chunks from less relevant groups to the most appropriate group

This process ensures that each file is modified in exactly one commit, while still maintaining semantic coherence within commits when possible.

Source code in src/codemap/git/semantic_grouping/resolver.py

class FileIntegrityResolver:
	"""
	Resolves file integrity constraints for semantic groups.

	File integrity refers to the requirement that all changes to a specific file should
	be included in the same commit, even if they are semantically different. This prevents
	fragmented changes to the same file across multiple commits, which can lead to broken builds
	or inconsistent states.

	The resolver works by:
	1. Identifying files that appear in multiple semantic groups
	2. Calculating the semantic similarity between these overlapping groups
	3. Either merging similar groups or reassigning chunks from less relevant groups
	   to the most appropriate group

	This process ensures that each file is modified in exactly one commit, while still
	maintaining semantic coherence within commits when possible.

	"""

	def __init__(self, similarity_threshold: float = 0.6) -> None:
		"""
		Initialize the resolver.

		Args:
		    similarity_threshold: Threshold for group similarity to trigger merging (0.0-1.0).
		        Higher values require greater similarity to merge groups:
		        - Values near 0.5 are permissive and will merge moderately related groups
		        - Values above 0.7 are strict and will mostly reassign chunks instead of merging
		        - Default 0.6 provides a balanced approach

		Raises:
		    ImportError: If scikit-learn is not installed

		"""
		self.similarity_threshold = similarity_threshold

		# Import here to avoid making sklearn a hard dependency
		try:
			from sklearn.metrics.pairwise import cosine_similarity

			self.cosine_similarity = cosine_similarity
		except ImportError as e:
			logger.exception("Failed to import scikit-learn. Please install it with: uv add scikit-learn")
			msg = "scikit-learn is required for file integrity resolution"
			raise ImportError(msg) from e

	def calculate_group_similarity(
		self, group1: "SemanticGroup", group2: "SemanticGroup", chunk_embeddings: dict[DiffChunk, np.ndarray]
	) -> float:
		"""
		Calculate similarity between two groups based on their chunks' embeddings.

		This method computes the average pairwise cosine similarity between all combinations
		of chunks from the two groups. The similarity is based on the semantic embeddings
		of the chunks' content.

		Process:
		1. Extract embeddings for all chunks in both groups
		2. Compute pairwise cosine similarities between each pair of chunks
		3. Return the average similarity score

		Args:
		    group1: First semantic group to compare
		    group2: Second semantic group to compare
		    chunk_embeddings: Dict mapping chunks to their embeddings

		Returns:
		    float: Similarity score between 0 and 1, where:
		        - 0 indicates completely unrelated changes
		        - 1 indicates identical or extremely similar changes
		        - Values around 0.6-0.8 typically indicate related functionality

		"""
		# Get embeddings for chunks in each group
		embeddings1 = [chunk_embeddings[chunk] for chunk in group1.chunks if chunk in chunk_embeddings]
		embeddings2 = [chunk_embeddings[chunk] for chunk in group2.chunks if chunk in chunk_embeddings]

		if not embeddings1 or not embeddings2:
			return 0.0

		# Calculate pairwise similarities
		similarities = []
		for emb1 in embeddings1:
			for emb2 in embeddings2:
				sim = self.cosine_similarity([emb1], [emb2])[0][0]
				similarities.append(sim)

		# Return average similarity
		return sum(similarities) / len(similarities) if similarities else 0.0

	def resolve_violations(
		self, groups: list["SemanticGroup"], chunk_embeddings: dict[DiffChunk, np.ndarray]
	) -> list["SemanticGroup"]:
		"""
		Resolve file integrity violations by merging or reassigning chunks.

		A violation occurs when the same file appears in multiple semantic groups.
		This needs to be resolved because a file should be modified in only one commit.

		Args:
		    groups: List of SemanticGroup objects to resolve
		    chunk_embeddings: Dict mapping chunks to their embeddings

		Returns:
		    List of SemanticGroup objects with all violations resolved

		"""
		# Keep iterating until no violations remain
		while True:
			# Build file to groups mapping
			file_to_groups: dict[str, list[int]] = {}
			for i, group in enumerate(groups):
				for file in group.files:
					if file not in file_to_groups:
						file_to_groups[file] = []
					file_to_groups[file].append(i)

			# Find violations (files in multiple groups)
			violations = {file: indices for file, indices in file_to_groups.items() if len(indices) > 1}

			if not violations:
				break  # No violations, we're done

			# Process the first violation
			file = next(iter(violations))
			group_indices = violations[file]

			# Try to find groups to merge based on similarity
			max_similarity = 0
			groups_to_merge = None

			# Calculate similarities between all pairs of groups containing this file
			for i in range(len(group_indices)):
				for j in range(i + 1, len(group_indices)):
					idx1, idx2 = group_indices[i], group_indices[j]
					similarity = self.calculate_group_similarity(groups[idx1], groups[idx2], chunk_embeddings)

					if similarity > max_similarity:
						max_similarity = similarity
						groups_to_merge = (idx1, idx2)

			# Decide whether to merge or reassign based on similarity threshold
			if max_similarity >= self.similarity_threshold and groups_to_merge:
				# STRATEGY 1: Merge groups if they're similar enough
				idx1, idx2 = groups_to_merge
				merged_group = groups[idx1].merge_with(groups[idx2])

				# Replace the first group with the merged one and remove the second
				groups[idx1] = merged_group
				groups.pop(idx2)
			else:
				# STRATEGY 2: Reassign chunks to the primary group for this file
				# Find the primary group (group with most chunks containing this file)
				file_chunks_count = []
				for idx in group_indices:
					count = sum(1 for chunk in groups[idx].chunks if file in chunk.files)
					file_chunks_count.append((idx, count))

				# Sort by count descending
				file_chunks_count.sort(key=lambda x: x[1], reverse=True)
				primary_idx = file_chunks_count[0][0]

				# Move chunks containing this file to the primary group
				for idx in group_indices:
					if idx != primary_idx:
						# Find chunks containing this file
						chunks_to_move = [chunk for chunk in groups[idx].chunks if file in chunk.files]

						# Move chunks to primary group
						groups[primary_idx].chunks.extend(chunks_to_move)

						# Remove moved chunks from original group
						groups[idx].chunks = [chunk for chunk in groups[idx].chunks if file not in chunk.files]

				# Remove empty groups
				groups = [group for group in groups if group.chunks]

		return groups

__init__

__init__(similarity_threshold: float = 0.6) -> None

Initialize the resolver.

Parameters:

Name	Type	Description	Default
similarity_threshold	float	Threshold for group similarity to trigger merging (0.0-1.0). Higher values require greater similarity to merge groups: - Values near 0.5 are permissive and will merge moderately related groups - Values above 0.7 are strict and will mostly reassign chunks instead of merging - Default 0.6 provides a balanced approach	0.6

Raises:

Type	Description
ImportError	If scikit-learn is not installed

Source code in src/codemap/git/semantic_grouping/resolver.py

def __init__(self, similarity_threshold: float = 0.6) -> None:
	"""
	Initialize the resolver.

	Args:
	    similarity_threshold: Threshold for group similarity to trigger merging (0.0-1.0).
	        Higher values require greater similarity to merge groups:
	        - Values near 0.5 are permissive and will merge moderately related groups
	        - Values above 0.7 are strict and will mostly reassign chunks instead of merging
	        - Default 0.6 provides a balanced approach

	Raises:
	    ImportError: If scikit-learn is not installed

	"""
	self.similarity_threshold = similarity_threshold

	# Import here to avoid making sklearn a hard dependency
	try:
		from sklearn.metrics.pairwise import cosine_similarity

		self.cosine_similarity = cosine_similarity
	except ImportError as e:
		logger.exception("Failed to import scikit-learn. Please install it with: uv add scikit-learn")
		msg = "scikit-learn is required for file integrity resolution"
		raise ImportError(msg) from e

similarity_threshold instance-attribute

similarity_threshold = similarity_threshold

cosine_similarity instance-attribute

cosine_similarity = cosine_similarity

calculate_group_similarity

calculate_group_similarity(
	group1: SemanticGroup,
	group2: SemanticGroup,
	chunk_embeddings: dict[DiffChunk, ndarray],
) -> float

Calculate similarity between two groups based on their chunks' embeddings.

This method computes the average pairwise cosine similarity between all combinations of chunks from the two groups. The similarity is based on the semantic embeddings of the chunks' content.

Process: 1. Extract embeddings for all chunks in both groups 2. Compute pairwise cosine similarities between each pair of chunks 3. Return the average similarity score

Parameters:

Name	Type	Description	Default
group1	SemanticGroup	First semantic group to compare	required
group2	SemanticGroup	Second semantic group to compare	required
chunk_embeddings	dict[DiffChunk, ndarray]	Dict mapping chunks to their embeddings	required

Returns:

Name	Type	Description
float	float	Similarity score between 0 and 1, where: - 0 indicates completely unrelated changes - 1 indicates identical or extremely similar changes - Values around 0.6-0.8 typically indicate related functionality

Source code in src/codemap/git/semantic_grouping/resolver.py

def calculate_group_similarity(
	self, group1: "SemanticGroup", group2: "SemanticGroup", chunk_embeddings: dict[DiffChunk, np.ndarray]
) -> float:
	"""
	Calculate similarity between two groups based on their chunks' embeddings.

	This method computes the average pairwise cosine similarity between all combinations
	of chunks from the two groups. The similarity is based on the semantic embeddings
	of the chunks' content.

	Process:
	1. Extract embeddings for all chunks in both groups
	2. Compute pairwise cosine similarities between each pair of chunks
	3. Return the average similarity score

	Args:
	    group1: First semantic group to compare
	    group2: Second semantic group to compare
	    chunk_embeddings: Dict mapping chunks to their embeddings

	Returns:
	    float: Similarity score between 0 and 1, where:
	        - 0 indicates completely unrelated changes
	        - 1 indicates identical or extremely similar changes
	        - Values around 0.6-0.8 typically indicate related functionality

	"""
	# Get embeddings for chunks in each group
	embeddings1 = [chunk_embeddings[chunk] for chunk in group1.chunks if chunk in chunk_embeddings]
	embeddings2 = [chunk_embeddings[chunk] for chunk in group2.chunks if chunk in chunk_embeddings]

	if not embeddings1 or not embeddings2:
		return 0.0

	# Calculate pairwise similarities
	similarities = []
	for emb1 in embeddings1:
		for emb2 in embeddings2:
			sim = self.cosine_similarity([emb1], [emb2])[0][0]
			similarities.append(sim)

	# Return average similarity
	return sum(similarities) / len(similarities) if similarities else 0.0

resolve_violations

resolve_violations(
	groups: list[SemanticGroup],
	chunk_embeddings: dict[DiffChunk, ndarray],
) -> list[SemanticGroup]

Resolve file integrity violations by merging or reassigning chunks.

A violation occurs when the same file appears in multiple semantic groups. This needs to be resolved because a file should be modified in only one commit.

Parameters:

Name	Type	Description	Default
groups	list[SemanticGroup]	List of SemanticGroup objects to resolve	required
chunk_embeddings	dict[DiffChunk, ndarray]	Dict mapping chunks to their embeddings	required

Returns:

Type	Description
list[SemanticGroup]	List of SemanticGroup objects with all violations resolved

Source code in src/codemap/git/semantic_grouping/resolver.py

def resolve_violations(
	self, groups: list["SemanticGroup"], chunk_embeddings: dict[DiffChunk, np.ndarray]
) -> list["SemanticGroup"]:
	"""
	Resolve file integrity violations by merging or reassigning chunks.

	A violation occurs when the same file appears in multiple semantic groups.
	This needs to be resolved because a file should be modified in only one commit.

	Args:
	    groups: List of SemanticGroup objects to resolve
	    chunk_embeddings: Dict mapping chunks to their embeddings

	Returns:
	    List of SemanticGroup objects with all violations resolved

	"""
	# Keep iterating until no violations remain
	while True:
		# Build file to groups mapping
		file_to_groups: dict[str, list[int]] = {}
		for i, group in enumerate(groups):
			for file in group.files:
				if file not in file_to_groups:
					file_to_groups[file] = []
				file_to_groups[file].append(i)

		# Find violations (files in multiple groups)
		violations = {file: indices for file, indices in file_to_groups.items() if len(indices) > 1}

		if not violations:
			break  # No violations, we're done

		# Process the first violation
		file = next(iter(violations))
		group_indices = violations[file]

		# Try to find groups to merge based on similarity
		max_similarity = 0
		groups_to_merge = None

		# Calculate similarities between all pairs of groups containing this file
		for i in range(len(group_indices)):
			for j in range(i + 1, len(group_indices)):
				idx1, idx2 = group_indices[i], group_indices[j]
				similarity = self.calculate_group_similarity(groups[idx1], groups[idx2], chunk_embeddings)

				if similarity > max_similarity:
					max_similarity = similarity
					groups_to_merge = (idx1, idx2)

		# Decide whether to merge or reassign based on similarity threshold
		if max_similarity >= self.similarity_threshold and groups_to_merge:
			# STRATEGY 1: Merge groups if they're similar enough
			idx1, idx2 = groups_to_merge
			merged_group = groups[idx1].merge_with(groups[idx2])

			# Replace the first group with the merged one and remove the second
			groups[idx1] = merged_group
			groups.pop(idx2)
		else:
			# STRATEGY 2: Reassign chunks to the primary group for this file
			# Find the primary group (group with most chunks containing this file)
			file_chunks_count = []
			for idx in group_indices:
				count = sum(1 for chunk in groups[idx].chunks if file in chunk.files)
				file_chunks_count.append((idx, count))

			# Sort by count descending
			file_chunks_count.sort(key=lambda x: x[1], reverse=True)
			primary_idx = file_chunks_count[0][0]

			# Move chunks containing this file to the primary group
			for idx in group_indices:
				if idx != primary_idx:
					# Find chunks containing this file
					chunks_to_move = [chunk for chunk in groups[idx].chunks if file in chunk.files]

					# Move chunks to primary group
					groups[primary_idx].chunks.extend(chunks_to_move)

					# Remove moved chunks from original group
					groups[idx].chunks = [chunk for chunk in groups[idx].chunks if file not in chunk.files]

			# Remove empty groups
			groups = [group for group in groups if group.chunks]

	return groups

context_processor

Context processing utilities for LLM prompts.

This module provides functionality to process and format code contexts for LLM prompts using tree-sitter analysis and Level of Detail (LOD) to optimize context length while preserving meaningful content.

logger module-attribute

logger = getLogger(__name__)

DEFAULT_MAX_TOKENS module-attribute

DEFAULT_MAX_TOKENS = 4000

CHUNK_TOKEN_ESTIMATE module-attribute

CHUNK_TOKEN_ESTIMATE = 500

MAX_CHUNKS module-attribute

MAX_CHUNKS = 6

MAX_SIMPLE_CHUNKS module-attribute

MAX_SIMPLE_CHUNKS = 3

process_chunks_with_lod

process_chunks_with_lod(
	chunks: list[DiffChunk],
	max_tokens: int = DEFAULT_MAX_TOKENS,
) -> str

Process diff chunks using LOD to create optimized context for LLM prompts.

Parameters:

Name	Type	Description	Default
chunks	list[DiffChunk]	List of diff chunks to process	required
max_tokens	int	Maximum tokens allowed in the formatted context	DEFAULT_MAX_TOKENS

Returns:

Type	Description
str	Formatted markdown context optimized for token usage

Source code in src/codemap/git/semantic_grouping/context_processor.py

def process_chunks_with_lod(chunks: list[DiffChunk], max_tokens: int = DEFAULT_MAX_TOKENS) -> str:
	"""
	Process diff chunks using LOD to create optimized context for LLM prompts.

	Args:
	    chunks: List of diff chunks to process
	    max_tokens: Maximum tokens allowed in the formatted context

	Returns:
	    Formatted markdown context optimized for token usage

	"""
	# If chunks list is small, we might not need LOD processing
	if len(chunks) <= MAX_SIMPLE_CHUNKS:
		return format_regular_chunks(chunks[:MAX_CHUNKS])

	# Set up LOD generator and estimate number of chunks we can include
	lod_generator = LODGenerator()
	estimated_chunk_count = min(max_tokens // CHUNK_TOKEN_ESTIMATE, len(chunks))
	prioritized_chunks = prioritize_chunks(chunks, min(estimated_chunk_count, MAX_CHUNKS))

	# Start with highest LOD level and progressively reduce if needed
	lod_levels = [LODLevel.STRUCTURE, LODLevel.SIGNATURES]
	formatted_chunks = []
	current_level_index = 0

	while current_level_index < len(lod_levels):
		current_level = lod_levels[current_level_index]
		formatted_chunks = []

		for chunk in prioritized_chunks:
			# Get file paths from chunk
			file_paths = get_file_paths_from_chunk(chunk)

			if not file_paths:
				# If we can't extract paths, use regular formatting for this chunk
				formatted_chunks.append(format_chunk(chunk))
				continue

			# Process each file in the chunk with LOD
			lod_formatted = []
			for file_path in file_paths:
				path = Path(file_path)
				if not path.exists():
					continue

				# Generate LOD representation
				lod_entity = lod_generator.generate_lod(path, level=current_level)
				if lod_entity:
					lod_formatted.append(format_lod_entity(lod_entity, file_path, current_level))

			if lod_formatted:
				formatted_chunks.append("\n".join(lod_formatted))
			else:
				# Fallback to regular formatting
				formatted_chunks.append(format_chunk(chunk))

		# Estimate if we're within token limit
		total_context = "\n\n".join(formatted_chunks)
		estimated_tokens = estimate_tokens(total_context)

		if estimated_tokens <= max_tokens or current_level_index == len(lod_levels) - 1:
			break

		# Try with lower LOD level
		current_level_index += 1

	# If we still exceed the token limit, truncate
	total_context = "\n\n".join(formatted_chunks)
	if estimate_tokens(total_context) > max_tokens:
		total_context = truncate_context(total_context, max_tokens)

	return total_context

prioritize_chunks

prioritize_chunks(
	chunks: list[DiffChunk], max_count: int
) -> list[DiffChunk]

Prioritize chunks based on heuristics (file types, changes, etc.).

This is a simple implementation that could be extended with more sophisticated dissimilarity metrics.

Parameters:

Name	Type	Description	Default
chunks	list[DiffChunk]	List of chunks to prioritize	required
max_count	int	Maximum number of chunks to return	required

Returns:

Type	Description
list[DiffChunk]	Prioritized list of chunks

Source code in src/codemap/git/semantic_grouping/context_processor.py

def prioritize_chunks(chunks: list[DiffChunk], max_count: int) -> list[DiffChunk]:
	"""
	Prioritize chunks based on heuristics (file types, changes, etc.).

	This is a simple implementation that could be extended with more
	sophisticated dissimilarity metrics.

	Args:
	    chunks: List of chunks to prioritize
	    max_count: Maximum number of chunks to return

	Returns:
	    Prioritized list of chunks

	"""
	# Simple heuristics for now:
	# 1. Prefer chunks with code files over non-code files
	# 2. Prefer chunks with more files (more central changes)
	# 3. Prefer chunks with more added/changed lines

	def chunk_score(chunk: DiffChunk) -> float:
		"""Calculates a priority score for a diff chunk based on heuristics.

		The score is calculated using three factors:
		1. Presence of code files (60% weight)
		2. Number of files affected (20% weight)
		3. Size of content changes (20% weight)

		Args:
			chunk: The diff chunk to score

		Returns:
			float: A score between 0 and 1 representing the chunk's priority
		"""
		# Check if any files are code files
		code_file_score = 0
		for file in chunk.files:
			if any(file.endswith(ext) for ext in [".py", ".js", ".ts", ".java", ".c", ".cpp", ".go"]):
				code_file_score = 1
				break

		# Score based on number of files
		file_count_score = min(len(chunk.files), 3) / 3

		# Score based on content size (as proxy for changes)
		content_score = min(len(chunk.content), 1000) / 1000

		return code_file_score * 0.6 + file_count_score * 0.2 + content_score * 0.2

	# Sort chunks by score and return top max_count
	return sorted(chunks, key=chunk_score, reverse=True)[:max_count]

get_file_paths_from_chunk

get_file_paths_from_chunk(chunk: DiffChunk) -> list[str]

Extract file paths from a diff chunk.

Parameters:

Name	Type	Description	Default
chunk	DiffChunk	The diff chunk to process	required

Returns:

Type	Description
list[str]	List of file paths

Source code in src/codemap/git/semantic_grouping/context_processor.py

def get_file_paths_from_chunk(chunk: DiffChunk) -> list[str]:
	"""
	Extract file paths from a diff chunk.

	Args:
	    chunk: The diff chunk to process

	Returns:
	    List of file paths

	"""
	return [file for file in chunk.files if file]

format_lod_entity

format_lod_entity(
	entity: LODEntity, file_path: str, level: LODLevel
) -> str

Format an LOD entity as GitHub-flavored markdown.

Parameters:

Name	Type	Description	Default
entity	LODEntity	The LOD entity to format	required
file_path	str	Path to the source file	required
level	LODLevel	LOD level used	required

Returns:

Type	Description
str	Formatted markdown string

Source code in src/codemap/git/semantic_grouping/context_processor.py

def format_lod_entity(entity: LODEntity, file_path: str, level: LODLevel) -> str:
	"""
	Format an LOD entity as GitHub-flavored markdown.

	Args:
	    entity: The LOD entity to format
	    file_path: Path to the source file
	    level: LOD level used

	Returns:
	    Formatted markdown string

	"""
	# Start with file header
	result = f"## {file_path}\n\n"

	# Format the entity based on LOD level
	if level == LODLevel.STRUCTURE:
		result += format_entity_structure(entity, 0)
	elif level == LODLevel.SIGNATURES:
		result += format_entity_signatures(entity, 0)

	return result

format_entity_structure

format_entity_structure(
	entity: LODEntity, indent: int
) -> str

Format entity with structure (signatures and hierarchy).

Source code in src/codemap/git/semantic_grouping/context_processor.py

def format_entity_structure(entity: LODEntity, indent: int) -> str:
	"""Format entity with structure (signatures and hierarchy)."""
	indent_str = "  " * indent
	result = f"{indent_str}- **{entity.entity_type.name}**: `{entity.name}`"

	if entity.signature:
		result += f"\n{indent_str}  ```\n{indent_str}  {entity.signature}\n{indent_str}  ```"

	if entity.children:
		result += "\n"
		for child in entity.children:
			result += format_entity_structure(child, indent + 1)

	return result + "\n"

format_entity_signatures

format_entity_signatures(
	entity: LODEntity, indent: int
) -> str

Format entity with just signatures.

Source code in src/codemap/git/semantic_grouping/context_processor.py

def format_entity_signatures(entity: LODEntity, indent: int) -> str:
	"""Format entity with just signatures."""
	indent_str = "  " * indent
	result = f"{indent_str}- **{entity.entity_type.name}**: `{entity.name}`"

	if entity.signature:
		result += f" - `{entity.signature}`"

	if entity.children:
		result += "\n"
		for child in entity.children:
			result += format_entity_signatures(child, indent + 1)

	return result + "\n"

format_regular_chunks

format_regular_chunks(chunks: list[DiffChunk]) -> str

Format chunks using the regular approach when LOD is not necessary.

Parameters:

Name	Type	Description	Default
chunks	list[DiffChunk]	List of chunks to format	required

Returns:

Type	Description
str	Formatted markdown string

Source code in src/codemap/git/semantic_grouping/context_processor.py

def format_regular_chunks(chunks: list[DiffChunk]) -> str:
	"""
	Format chunks using the regular approach when LOD is not necessary.

	Args:
	    chunks: List of chunks to format

	Returns:
	    Formatted markdown string

	"""
	formatted_chunks = [format_chunk(chunk) for chunk in chunks]
	return "\n\n".join(formatted_chunks)

format_chunk

format_chunk(chunk: DiffChunk) -> str

Format a single diff chunk as markdown.

Parameters:

Name	Type	Description	Default
chunk	DiffChunk	The diff chunk to format	required

Returns:

Type	Description
str	Formatted markdown string

Source code in src/codemap/git/semantic_grouping/context_processor.py

def format_chunk(chunk: DiffChunk) -> str:
	"""
	Format a single diff chunk as markdown.

	Args:
	    chunk: The diff chunk to format

	Returns:
	    Formatted markdown string

	"""
	# Format file paths
	file_section = "## Files\n"
	for file in chunk.files:
		if file:
			file_section += f"- {file}\n"

	# Format content
	content_section = "### Changes\n```diff\n" + chunk.content + "\n```"

	return file_section + "\n" + content_section

estimate_tokens

estimate_tokens(text: str) -> int

Estimate the number of tokens in a text.

This is a simple estimation that can be improved with actual tokenizer implementations if needed.

Parameters:

Name	Type	Description	Default
text	str	Text to estimate tokens for	required

Returns:

Type	Description
int	Estimated token count

Source code in src/codemap/git/semantic_grouping/context_processor.py

def estimate_tokens(text: str) -> int:
	"""
	Estimate the number of tokens in a text.

	This is a simple estimation that can be improved with
	actual tokenizer implementations if needed.

	Args:
	    text: Text to estimate tokens for

	Returns:
	    Estimated token count

	"""
	# Simple estimation: 4 characters per token on average
	return len(text) // 4

truncate_context

truncate_context(context: str, max_tokens: int) -> str

Truncate context to fit within token limit.

Parameters:

Name	Type	Description	Default
context	str	Context to truncate	required
max_tokens	int	Maximum allowed tokens	required

Returns:

Type	Description
str	Truncated context

Source code in src/codemap/git/semantic_grouping/context_processor.py

def truncate_context(context: str, max_tokens: int) -> str:
	"""
	Truncate context to fit within token limit.

	Args:
	    context: Context to truncate
	    max_tokens: Maximum allowed tokens

	Returns:
	    Truncated context

	"""
	# Simple truncation by estimating tokens
	if estimate_tokens(context) <= max_tokens:
		return context

	# Split into chunks and preserve as many complete chunks as possible
	chunks = context.split("\n\n")
	result_chunks = []
	current_token_count = 0

	for chunk in chunks:
		chunk_tokens = estimate_tokens(chunk)
		if current_token_count + chunk_tokens <= max_tokens - 100:  # Reserve 100 tokens for truncation marker
			result_chunks.append(chunk)
			current_token_count += chunk_tokens
		else:
			# Add truncation marker and stop
			result_chunks.append("\n\n[...TRUNCATED...]\n\n")
			break

	return "\n\n".join(result_chunks)

group

Module for semantic grouping of diff chunks.

SemanticGroup

Represents a group of semantically related diff chunks.

Source code in src/codemap/git/semantic_grouping/group.py

class SemanticGroup:
	"""Represents a group of semantically related diff chunks."""

	def __init__(self, chunks: list[DiffChunk] | None = None, name: str | None = None) -> None:
		"""
		Initialize a semantic group.

		Args:
		    chunks: List of DiffChunk objects
		    name: Optional name for the group

		"""
		self.chunks = chunks or []
		self.name = name
		self.message: str | None = None
		self.approved = False

	@property
	def files(self) -> list[str]:
		"""Get the set of files affected by this group."""
		files: set[str] = set()
		for chunk in self.chunks:
			files.update(chunk.files)
		return sorted(files)

	@property
	def content(self) -> str:
		"""Get the combined diff content of all chunks."""
		return "\n".join(chunk.content for chunk in self.chunks)

	def merge_with(self, other_group: "SemanticGroup") -> "SemanticGroup":
		"""
		Merge this group with another group.

		Args:
		    other_group: Another SemanticGroup to merge with

		Returns:
		    A new SemanticGroup containing chunks from both groups

		"""
		return SemanticGroup(
			chunks=self.chunks + other_group.chunks, name=f"Merged: {self.name or ''} + {other_group.name or ''}"
		)

	def __repr__(self) -> str:
		"""Return a string representation of the group with file and chunk counts."""
		return f"SemanticGroup(files={len(self.files)}, chunks={len(self.chunks)})"

__init__

__init__(
	chunks: list[DiffChunk] | None = None,
	name: str | None = None,
) -> None

Initialize a semantic group.

Parameters:

Name	Type	Description	Default
chunks	list[DiffChunk] | None	List of DiffChunk objects	None
name	str | None	Optional name for the group	None

Source code in src/codemap/git/semantic_grouping/group.py

def __init__(self, chunks: list[DiffChunk] | None = None, name: str | None = None) -> None:
	"""
	Initialize a semantic group.

	Args:
	    chunks: List of DiffChunk objects
	    name: Optional name for the group

	"""
	self.chunks = chunks or []
	self.name = name
	self.message: str | None = None
	self.approved = False

chunks instance-attribute

chunks = chunks or []

name instance-attribute

name = name

message instance-attribute

message: str | None = None

approved instance-attribute

approved = False

files property

files: list[str]

Get the set of files affected by this group.

content property

content: str

Get the combined diff content of all chunks.

merge_with

merge_with(other_group: SemanticGroup) -> SemanticGroup

Merge this group with another group.

Parameters:

Name	Type	Description	Default
other_group	SemanticGroup	Another SemanticGroup to merge with	required

Returns:

Type	Description
SemanticGroup	A new SemanticGroup containing chunks from both groups

Source code in src/codemap/git/semantic_grouping/group.py

def merge_with(self, other_group: "SemanticGroup") -> "SemanticGroup":
	"""
	Merge this group with another group.

	Args:
	    other_group: Another SemanticGroup to merge with

	Returns:
	    A new SemanticGroup containing chunks from both groups

	"""
	return SemanticGroup(
		chunks=self.chunks + other_group.chunks, name=f"Merged: {self.name or ''} + {other_group.name or ''}"
	)

__repr__

__repr__() -> str

Return a string representation of the group with file and chunk counts.

Source code in src/codemap/git/semantic_grouping/group.py

def __repr__(self) -> str:
	"""Return a string representation of the group with file and chunk counts."""
	return f"SemanticGroup(files={len(self.files)}, chunks={len(self.chunks)})"

embedder

Module for generating embeddings from diff chunks.

logger module-attribute

logger = getLogger(__name__)

DiffEmbedder

Generates embeddings for diff chunks.

Source code in src/codemap/git/semantic_grouping/embedder.py

class DiffEmbedder:
	"""Generates embeddings for diff chunks."""

	def __init__(self, model_name: str = "all-MiniLM-L6-v2") -> None:
		"""
		Initialize the embedder with a specific model.

		Args:
		    model_name: Name of the sentence-transformers model to use

		"""
		# Import here to avoid making sentence-transformers a hard dependency
		try:
			from sentence_transformers import SentenceTransformer

			self.model = SentenceTransformer(model_name)
		except ImportError as e:
			logger.exception(
				"Failed to import sentence-transformers. Please install it with: uv add sentence-transformers"
			)
			msg = "sentence-transformers is required for semantic grouping"
			raise ImportError(msg) from e

	def preprocess_diff(self, diff_text: str) -> str:
		"""
		Preprocess diff text to make it more suitable for embedding.

		Args:
		    diff_text: Raw diff text

		Returns:
		    Preprocessed text

		"""
		# Remove diff headers, line numbers, etc.
		# Focus on actual content changes
		lines = []
		for line in diff_text.splitlines():
			# Skip diff metadata lines
			if line.startswith(("diff --git", "index ", "+++", "---")):
				continue

			# Keep actual content changes, removing the +/- prefix
			if line.startswith(("+", "-", " ")):
				lines.append(line[1:])

		return "\n".join(lines)

	def embed_chunk(self, chunk: DiffChunk) -> np.ndarray:
		"""
		Generate an embedding for a diff chunk.

		Args:
		    chunk: DiffChunk object

		Returns:
		    numpy.ndarray: Embedding vector

		"""
		# Get the diff content from the chunk
		diff_text = chunk.content

		# Preprocess the diff text
		processed_text = self.preprocess_diff(diff_text)

		# If the processed text is empty, use the file paths as context
		if not processed_text.strip():
			processed_text = " ".join(chunk.files)

		# Generate the embedding and convert to numpy array
		embedding = self.model.encode(processed_text)
		return np.array(embedding)

	def embed_chunks(self, chunks: list[DiffChunk]) -> list[tuple[DiffChunk, np.ndarray]]:
		"""
		Generate embeddings for multiple chunks.

		Args:
		    chunks: List of DiffChunk objects

		Returns:
		    List of (chunk, embedding) tuples

		"""
		return [(chunk, self.embed_chunk(chunk)) for chunk in chunks]

__init__

__init__(model_name: str = 'all-MiniLM-L6-v2') -> None

Initialize the embedder with a specific model.

Parameters:

Name	Type	Description	Default
model_name	str	Name of the sentence-transformers model to use	'all-MiniLM-L6-v2'

Source code in src/codemap/git/semantic_grouping/embedder.py

def __init__(self, model_name: str = "all-MiniLM-L6-v2") -> None:
	"""
	Initialize the embedder with a specific model.

	Args:
	    model_name: Name of the sentence-transformers model to use

	"""
	# Import here to avoid making sentence-transformers a hard dependency
	try:
		from sentence_transformers import SentenceTransformer

		self.model = SentenceTransformer(model_name)
	except ImportError as e:
		logger.exception(
			"Failed to import sentence-transformers. Please install it with: uv add sentence-transformers"
		)
		msg = "sentence-transformers is required for semantic grouping"
		raise ImportError(msg) from e

model instance-attribute

model = SentenceTransformer(model_name)

preprocess_diff

preprocess_diff(diff_text: str) -> str

Preprocess diff text to make it more suitable for embedding.

Parameters:

Name	Type	Description	Default
diff_text	str	Raw diff text	required

Returns:

Type	Description
str	Preprocessed text

Source code in src/codemap/git/semantic_grouping/embedder.py

def preprocess_diff(self, diff_text: str) -> str:
	"""
	Preprocess diff text to make it more suitable for embedding.

	Args:
	    diff_text: Raw diff text

	Returns:
	    Preprocessed text

	"""
	# Remove diff headers, line numbers, etc.
	# Focus on actual content changes
	lines = []
	for line in diff_text.splitlines():
		# Skip diff metadata lines
		if line.startswith(("diff --git", "index ", "+++", "---")):
			continue

		# Keep actual content changes, removing the +/- prefix
		if line.startswith(("+", "-", " ")):
			lines.append(line[1:])

	return "\n".join(lines)

embed_chunk

embed_chunk(chunk: DiffChunk) -> ndarray

Generate an embedding for a diff chunk.

Parameters:

Name	Type	Description	Default
chunk	DiffChunk	DiffChunk object	required

Returns:

Type	Description
ndarray	numpy.ndarray: Embedding vector

Source code in src/codemap/git/semantic_grouping/embedder.py

def embed_chunk(self, chunk: DiffChunk) -> np.ndarray:
	"""
	Generate an embedding for a diff chunk.

	Args:
	    chunk: DiffChunk object

	Returns:
	    numpy.ndarray: Embedding vector

	"""
	# Get the diff content from the chunk
	diff_text = chunk.content

	# Preprocess the diff text
	processed_text = self.preprocess_diff(diff_text)

	# If the processed text is empty, use the file paths as context
	if not processed_text.strip():
		processed_text = " ".join(chunk.files)

	# Generate the embedding and convert to numpy array
	embedding = self.model.encode(processed_text)
	return np.array(embedding)

embed_chunks

embed_chunks(
	chunks: list[DiffChunk],
) -> list[tuple[DiffChunk, ndarray]]

Generate embeddings for multiple chunks.

Parameters:

Name	Type	Description	Default
chunks	list[DiffChunk]	List of DiffChunk objects	required

Returns:

Type	Description
list[tuple[DiffChunk, ndarray]]	List of (chunk, embedding) tuples

Source code in src/codemap/git/semantic_grouping/embedder.py

def embed_chunks(self, chunks: list[DiffChunk]) -> list[tuple[DiffChunk, np.ndarray]]:
	"""
	Generate embeddings for multiple chunks.

	Args:
	    chunks: List of DiffChunk objects

	Returns:
	    List of (chunk, embedding) tuples

	"""
	return [(chunk, self.embed_chunk(chunk)) for chunk in chunks]

clusterer

Module for clustering diff chunks based on their embeddings.

This module provides functionality to group related code changes together based on their semantic similarity, using vector embeddings and clustering algorithms. The clustering process helps identify related changes that should be committed together.

Key components: - DiffClusterer: Main class that implements clustering algorithms for diff chunks - ClusteringParams: Type definition for parameters used by clustering algorithms

The module supports multiple clustering methods: 1. Agglomerative (hierarchical) clustering: Builds a hierarchy of clusters based on distances between embeddings, using a distance threshold to determine final cluster boundaries 2. DBSCAN: Density-based clustering that groups points in high-density regions, treating low-density points as noise/outliers

logger module-attribute

logger = getLogger(__name__)

ClusteringParams

Bases: TypedDict

Type definition for clustering algorithm parameters.

These parameters configure the behavior of the clustering algorithms:

For agglomerative clustering: - n_clusters: Optional limit on number of clusters (None means no limit) - distance_threshold: Maximum distance for clusters to be merged (lower = more clusters) - metric: Distance metric to use (e.g., "precomputed" for precomputed distance matrix) - linkage: Strategy for calculating distances between clusters ("average", "single", etc.)

For DBSCAN: - eps: Maximum distance between points in the same neighborhood - min_samples: Minimum points required to form a dense region - metric: Distance metric to use

Source code in src/codemap/git/semantic_grouping/clusterer.py

class ClusteringParams(TypedDict, total=False):
	"""
	Type definition for clustering algorithm parameters.

	These parameters configure the behavior of the clustering algorithms:

	For agglomerative clustering:
	- n_clusters: Optional limit on number of clusters (None means no limit)
	- distance_threshold: Maximum distance for clusters to be merged (lower = more clusters)
	- metric: Distance metric to use (e.g., "precomputed" for precomputed distance matrix)
	- linkage: Strategy for calculating distances between clusters ("average", "single", etc.)

	For DBSCAN:
	- eps: Maximum distance between points in the same neighborhood
	- min_samples: Minimum points required to form a dense region
	- metric: Distance metric to use

	"""

	n_clusters: int | None
	distance_threshold: float | None
	metric: str
	linkage: str
	eps: float
	min_samples: int

n_clusters instance-attribute

n_clusters: int | None

distance_threshold instance-attribute

distance_threshold: float | None

metric instance-attribute

metric: str

linkage instance-attribute

linkage: str

eps instance-attribute

eps: float

min_samples instance-attribute

min_samples: int

T module-attribute

T = TypeVar('T')

DiffClusterer

Clusters diff chunks based on their semantic embeddings.

This class provides methods to group related code changes by their semantic similarity, using vector embeddings and standard clustering algorithms from scikit-learn.

Clustering helps identify code changes that are related to each other and should be grouped in the same commit, even if they appear in different files.

The class supports multiple clustering algorithms: 1. Agglomerative clustering: Hierarchical clustering that's good for finding natural groupings without needing to specify the exact number of clusters 2. DBSCAN: Density-based clustering that can identify outliers and works well with irregularly shaped clusters

Source code in src/codemap/git/semantic_grouping/clusterer.py

class DiffClusterer:
	"""
	Clusters diff chunks based on their semantic embeddings.

	This class provides methods to group related code changes by their semantic similarity,
	using vector embeddings and standard clustering algorithms from scikit-learn.

	Clustering helps identify code changes that are related to each other and should be
	grouped in the same commit, even if they appear in different files.

	The class supports multiple clustering algorithms:
	1. Agglomerative clustering: Hierarchical clustering that's good for finding natural
	   groupings without needing to specify the exact number of clusters
	2. DBSCAN: Density-based clustering that can identify outliers and works well with
	   irregularly shaped clusters

	"""

	def __init__(self, method: str = "agglomerative", **kwargs: object) -> None:
		"""
		Initialize the clusterer.

		Args:
		    method: Clustering method to use. Options:
		        - "agglomerative": Hierarchical clustering (default)
		        - "dbscan": Density-based spatial clustering
		    **kwargs: Additional parameters for the clustering algorithm:
		        - For agglomerative: distance_threshold, linkage, etc.
		        - For DBSCAN: eps, min_samples, etc.

		Raises:
		    ImportError: If scikit-learn is not installed

		"""
		self.method = method
		self.kwargs = kwargs

		# Import here to avoid making sklearn a hard dependency
		try:
			from sklearn.cluster import DBSCAN, AgglomerativeClustering
			from sklearn.metrics.pairwise import cosine_similarity

			self.AgglomerativeClustering = AgglomerativeClustering
			self.DBSCAN = DBSCAN
			self.cosine_similarity = cosine_similarity
		except ImportError as e:
			logger.exception("Failed to import scikit-learn. Please install it with: uv add scikit-learn")
			msg = "scikit-learn is required for clustering"
			raise ImportError(msg) from e

	def cluster(self, chunk_embeddings: list[tuple[DiffChunk, np.ndarray]]) -> list[list[DiffChunk]]:
		"""
		Cluster chunks based on their embeddings.

		              Process:
		              1. Extracts chunks and embeddings from input tuples
		              2. Computes a similarity matrix using cosine similarity
		              3. Converts similarity to distance matrix (1 - similarity)
		              4. Applies clustering algorithm based on the chosen method
		              5. Organizes chunks into clusters based on labels
		              6. Handles special cases like noise points in DBSCAN

		Args:
		    chunk_embeddings: List of (chunk, embedding) tuples where each embedding
		        is a numpy array representing the semantic vector of a code chunk

		Returns:
		    List of lists, where each inner list contains chunks in the same cluster.
		    With DBSCAN, noise points (label -1) are returned as individual single-item clusters.

		Examples:
		    >>> embedder = DiffEmbedder()
		    >>> chunk_embeddings = embedder.embed_chunks(diff_chunks)
		    >>> clusterer = DiffClusterer(method="agglomerative", distance_threshold=0.5)
		    >>> clusters = clusterer.cluster(chunk_embeddings)
		    >>> for i, cluster in enumerate(clusters):
		    ...     print(f"Cluster {i} has {len(cluster)} chunks")

		"""
		if not chunk_embeddings:
			return []

		# Extract chunks and embeddings
		chunks = [ce[0] for ce in chunk_embeddings]
		embeddings = np.array([ce[1] for ce in chunk_embeddings])

		# Compute similarity matrix (1 - cosine distance)
		similarity_matrix = self.cosine_similarity(embeddings)

		# Convert to distance matrix (1 - similarity)
		distance_matrix = 1 - similarity_matrix

		# Apply clustering
		if self.method == "agglomerative":
			# Default parameters if not provided
			params = {
				"n_clusters": None,
				"distance_threshold": 0.5,  # Threshold for cluster formation (0.5 = moderate similarity)
				"metric": "precomputed",  # Use metric instead of affinity
				"linkage": "average",  # Use average linkage for balanced clusters
			}
			params.update(self.kwargs)

			clustering = self.AgglomerativeClustering(**params)
			labels = clustering.fit_predict(distance_matrix)

		elif self.method == "dbscan":
			# Default parameters if not provided
			params = {
				"eps": 0.3,  # Maximum distance between points in neighborhood (0.3 = high similarity required)
				"min_samples": 2,  # Minimum points to form a dense region
				"metric": "precomputed",  # Using precomputed distance matrix
			}
			params.update(self.kwargs)

			clustering = self.DBSCAN(**params)
			labels = clustering.fit_predict(distance_matrix)

		else:
			msg = f"Unsupported clustering method: {self.method}"
			raise ValueError(msg)

		# Group chunks by cluster label
		clusters: dict[int, list[DiffChunk]] = {}
		for i, label in enumerate(labels):
			# Convert numpy integer to Python int
			label_key = int(label)
			if label_key not in clusters:
				clusters[label_key] = []
			clusters[label_key].append(chunks[i])

		# Convert to list of lists and handle noise points (-1 label in DBSCAN)
		result: list[list[DiffChunk]] = []
		for label, cluster_chunks in sorted(clusters.items()):
			if label != -1:  # Regular cluster
				result.append(cluster_chunks)
			else:  # Noise points - each forms its own cluster
				result.extend([[chunk] for chunk in cluster_chunks])

		return result

__init__

__init__(
	method: str = "agglomerative", **kwargs: object
) -> None

Initialize the clusterer.

Parameters:

Name	Type	Description	Default
method	str	Clustering method to use. Options: - "agglomerative": Hierarchical clustering (default) - "dbscan": Density-based spatial clustering	'agglomerative'
**kwargs	object	Additional parameters for the clustering algorithm: - For agglomerative: distance_threshold, linkage, etc. - For DBSCAN: eps, min_samples, etc.	{}

Raises:

Type	Description
ImportError	If scikit-learn is not installed

Source code in src/codemap/git/semantic_grouping/clusterer.py

def __init__(self, method: str = "agglomerative", **kwargs: object) -> None:
	"""
	Initialize the clusterer.

	Args:
	    method: Clustering method to use. Options:
	        - "agglomerative": Hierarchical clustering (default)
	        - "dbscan": Density-based spatial clustering
	    **kwargs: Additional parameters for the clustering algorithm:
	        - For agglomerative: distance_threshold, linkage, etc.
	        - For DBSCAN: eps, min_samples, etc.

	Raises:
	    ImportError: If scikit-learn is not installed

	"""
	self.method = method
	self.kwargs = kwargs

	# Import here to avoid making sklearn a hard dependency
	try:
		from sklearn.cluster import DBSCAN, AgglomerativeClustering
		from sklearn.metrics.pairwise import cosine_similarity

		self.AgglomerativeClustering = AgglomerativeClustering
		self.DBSCAN = DBSCAN
		self.cosine_similarity = cosine_similarity
	except ImportError as e:
		logger.exception("Failed to import scikit-learn. Please install it with: uv add scikit-learn")
		msg = "scikit-learn is required for clustering"
		raise ImportError(msg) from e

method instance-attribute

method = method

kwargs instance-attribute

kwargs = kwargs

AgglomerativeClustering instance-attribute

AgglomerativeClustering = AgglomerativeClustering

DBSCAN instance-attribute

DBSCAN = DBSCAN

cosine_similarity instance-attribute

cosine_similarity = cosine_similarity

cluster

cluster(
	chunk_embeddings: list[tuple[DiffChunk, ndarray]],
) -> list[list[DiffChunk]]

Cluster chunks based on their embeddings.

          Process:
          1. Extracts chunks and embeddings from input tuples
          2. Computes a similarity matrix using cosine similarity
          3. Converts similarity to distance matrix (1 - similarity)
          4. Applies clustering algorithm based on the chosen method
          5. Organizes chunks into clusters based on labels
          6. Handles special cases like noise points in DBSCAN

Parameters:

Name	Type	Description	Default
chunk_embeddings	list[tuple[DiffChunk, ndarray]]	List of (chunk, embedding) tuples where each embedding is a numpy array representing the semantic vector of a code chunk	required

Returns:

Type	Description
list[list[DiffChunk]]	List of lists, where each inner list contains chunks in the same cluster.
list[list[DiffChunk]]	With DBSCAN, noise points (label -1) are returned as individual single-item clusters.

Examples:

>>> embedder = DiffEmbedder()
>>> chunk_embeddings = embedder.embed_chunks(diff_chunks)
>>> clusterer = DiffClusterer(method="agglomerative", distance_threshold=0.5)
>>> clusters = clusterer.cluster(chunk_embeddings)
>>> for i, cluster in enumerate(clusters):
...     print(f"Cluster {i} has {len(cluster)} chunks")

Source code in src/codemap/git/semantic_grouping/clusterer.py

def cluster(self, chunk_embeddings: list[tuple[DiffChunk, np.ndarray]]) -> list[list[DiffChunk]]:
	"""
	Cluster chunks based on their embeddings.

	              Process:
	              1. Extracts chunks and embeddings from input tuples
	              2. Computes a similarity matrix using cosine similarity
	              3. Converts similarity to distance matrix (1 - similarity)
	              4. Applies clustering algorithm based on the chosen method
	              5. Organizes chunks into clusters based on labels
	              6. Handles special cases like noise points in DBSCAN

	Args:
	    chunk_embeddings: List of (chunk, embedding) tuples where each embedding
	        is a numpy array representing the semantic vector of a code chunk

	Returns:
	    List of lists, where each inner list contains chunks in the same cluster.
	    With DBSCAN, noise points (label -1) are returned as individual single-item clusters.

	Examples:
	    >>> embedder = DiffEmbedder()
	    >>> chunk_embeddings = embedder.embed_chunks(diff_chunks)
	    >>> clusterer = DiffClusterer(method="agglomerative", distance_threshold=0.5)
	    >>> clusters = clusterer.cluster(chunk_embeddings)
	    >>> for i, cluster in enumerate(clusters):
	    ...     print(f"Cluster {i} has {len(cluster)} chunks")

	"""
	if not chunk_embeddings:
		return []

	# Extract chunks and embeddings
	chunks = [ce[0] for ce in chunk_embeddings]
	embeddings = np.array([ce[1] for ce in chunk_embeddings])

	# Compute similarity matrix (1 - cosine distance)
	similarity_matrix = self.cosine_similarity(embeddings)

	# Convert to distance matrix (1 - similarity)
	distance_matrix = 1 - similarity_matrix

	# Apply clustering
	if self.method == "agglomerative":
		# Default parameters if not provided
		params = {
			"n_clusters": None,
			"distance_threshold": 0.5,  # Threshold for cluster formation (0.5 = moderate similarity)
			"metric": "precomputed",  # Use metric instead of affinity
			"linkage": "average",  # Use average linkage for balanced clusters
		}
		params.update(self.kwargs)

		clustering = self.AgglomerativeClustering(**params)
		labels = clustering.fit_predict(distance_matrix)

	elif self.method == "dbscan":
		# Default parameters if not provided
		params = {
			"eps": 0.3,  # Maximum distance between points in neighborhood (0.3 = high similarity required)
			"min_samples": 2,  # Minimum points to form a dense region
			"metric": "precomputed",  # Using precomputed distance matrix
		}
		params.update(self.kwargs)

		clustering = self.DBSCAN(**params)
		labels = clustering.fit_predict(distance_matrix)

	else:
		msg = f"Unsupported clustering method: {self.method}"
		raise ValueError(msg)

	# Group chunks by cluster label
	clusters: dict[int, list[DiffChunk]] = {}
	for i, label in enumerate(labels):
		# Convert numpy integer to Python int
		label_key = int(label)
		if label_key not in clusters:
			clusters[label_key] = []
		clusters[label_key].append(chunks[i])

	# Convert to list of lists and handle noise points (-1 label in DBSCAN)
	result: list[list[DiffChunk]] = []
	for label, cluster_chunks in sorted(clusters.items()):
		if label != -1:  # Regular cluster
			result.append(cluster_chunks)
		else:  # Noise points - each forms its own cluster
			result.extend([[chunk] for chunk in cluster_chunks])

	return result

pr_generator

PR generation package for CodeMap.

This package provides modules for generating and managing pull requests.

git_operation

git_operation(func: F) -> F

Decorator for git operations.

This decorator wraps functions that perform git operations, providing: - Logging of operation start/end - Standardized error handling - Automatic conversion of git-related exceptions to GitError

Parameters:

Name	Type	Description	Default
func	F	The function to decorate	required

Returns:

Type	Description
F	Decorated function

Source code in src/codemap/git/pr_generator/decorators.py

def git_operation(func: F) -> F:
	"""
	Decorator for git operations.

	This decorator wraps functions that perform git operations, providing:
	- Logging of operation start/end
	- Standardized error handling
	- Automatic conversion of git-related exceptions to GitError

	Args:
	    func: The function to decorate

	Returns:
	    Decorated function

	"""

	@functools.wraps(func)
	def wrapper(*args: object, **kwargs: object) -> object:
		"""Wrapper function for git operations that handles logging and error conversion.

		Args:
		    *args: Positional arguments passed to the decorated function.
		    **kwargs: Keyword arguments passed to the decorated function.

		Returns:
		    The result of the decorated function if successful.

		Raises:
		    GitError: If any exception occurs during the git operation. Original GitError
		        exceptions are re-raised as-is, while other exceptions are converted to
		        GitError with a descriptive message.

		Note:
		    - Logs debug messages for operation start/end
		    - Converts non-GitError exceptions to GitError
		    - Preserves original GitError exceptions
		"""
		function_name = func.__name__
		logger.debug("Starting git operation: %s", function_name)

		try:
			result = func(*args, **kwargs)
			logger.debug("Completed git operation: %s", function_name)
			return result
		except GitError:
			# Re-raise GitError as is
			logger.debug("GitError in operation: %s", function_name)
			raise
		except Exception as e:
			# Convert other exceptions to GitError
			logger.debug("Error in git operation %s: %s", function_name, str(e))
			msg = f"Git operation failed: {function_name} - {e!s}"
			raise GitError(msg) from e

	return cast("F", wrapper)

PRGenerator

Generator for Pull Requests.

This class handles generating pull request content (title and description) and creating/updating PRs on GitHub.

Source code in src/codemap/git/pr_generator/generator.py

class PRGenerator:
	"""
	Generator for Pull Requests.

	This class handles generating pull request content (title and
	description) and creating/updating PRs on GitHub.

	"""

	def __init__(
		self,
		repo_path: Path,
		llm_client: LLMClient,
	) -> None:
		"""
		Initialize the PR generator.

		Args:
		    repo_path: Path to the git repository
		    llm_client: LLMClient instance to use for content generation

		"""
		self.repo_path = repo_path
		self.client = llm_client

	def generate_content_from_commits(self, base_branch: str, head_branch: str, use_llm: bool = True) -> PRContent:
		"""
		Generate PR content (title and description) from commits.

		Args:
		    base_branch: Base branch (e.g., main)
		    head_branch: Head branch (e.g., feature-branch)
		    use_llm: Whether to use LLM for generation

		Returns:
		    Dictionary with 'title' and 'description' keys

		"""
		# Get commit messages between branches
		commits = get_commit_messages(base_branch, head_branch)

		if not commits:
			return {"title": "Update branch", "description": "No changes in this PR."}

		if use_llm:
			# Generate title and description using LLM
			title = generate_pr_title_with_llm(commits, self.client)
			description = generate_pr_description_with_llm(commits, self.client)
		else:
			# Generate title and description using rule-based approach
			title = generate_pr_title_from_commits(commits)
			description = generate_pr_description_from_commits(commits)

		return {"title": title, "description": description}

	def generate_content_from_template(
		self, branch_name: str, description: str, workflow_strategy: str = "github-flow"
	) -> PRContent:
		"""
		Generate PR content (title and description) from a template.

		Args:
		    branch_name: Name of the branch
		    description: Short description of the changes
		    workflow_strategy: Git workflow strategy to use

		Returns:
		    Dictionary with 'title' and 'description' keys

		"""
		return generate_pr_content_from_template(branch_name, description, workflow_strategy)

	def suggest_branch_name(self, description: str, workflow_strategy: str = "github-flow") -> str:
		"""
		Suggest a branch name based on a description.

		Args:
		    description: Description of the branch
		    workflow_strategy: Git workflow strategy to use

		Returns:
		    Suggested branch name

		"""
		return suggest_branch_name(description, workflow_strategy)

	def create_pr(self, base_branch: str, head_branch: str, title: str, description: str) -> PullRequest:
		"""
		Create a pull request on GitHub.

		Args:
		    base_branch: Base branch (e.g., main)
		    head_branch: Head branch (e.g., feature-branch)
		    title: PR title
		    description: PR description

		Returns:
		    PullRequest object with PR details

		Raises:
		    GitError: If PR creation fails

		"""
		return create_pull_request(base_branch, head_branch, title, description)

	def update_pr(self, pr_number: int, title: str, description: str) -> PullRequest:
		"""
		Update an existing pull request.

		Args:
		    pr_number: PR number
		    title: New PR title
		    description: New PR description

		Returns:
		    Updated PullRequest object

		Raises:
		    GitError: If PR update fails

		"""
		return update_pull_request(pr_number, title, description)

	def get_existing_pr(self, branch_name: str) -> PullRequest | None:
		"""
		Get an existing PR for a branch.

		Args:
		    branch_name: Branch name

		Returns:
		    PullRequest object if found, None otherwise

		"""
		return get_existing_pr(branch_name)

	def create_or_update_pr(
		self,
		base_branch: str | None = None,
		head_branch: str | None = None,
		title: str | None = None,
		description: str | None = None,
		use_llm: bool = True,
		pr_number: int | None = None,
	) -> PullRequest:
		"""
		Create a new PR or update an existing one.

		Args:
		    base_branch: Base branch (defaults to default branch)
		    head_branch: Head branch
		    title: PR title (if None, will be generated)
		    description: PR description (if None, will be generated)
		    use_llm: Whether to use LLM for content generation
		    pr_number: PR number for update (if None, will create new PR)

		Returns:
		    PullRequest object

		Raises:
		    GitError: If PR creation/update fails

		"""
		# Get default branch if base_branch is not specified
		if base_branch is None:
			base_branch = get_default_branch()

		# Set default head_branch to current branch if not specified
		if head_branch is None:
			try:
				from codemap.git.pr_generator.utils import get_current_branch

				head_branch = get_current_branch()
			except GitError as err:
				msg = "Failed to determine current branch"
				raise GitError(msg) from err

		# Check if PR exists
		existing_pr = None
		if pr_number is not None:
			# Updating an existing PR by number
			if title is None or description is None:
				# Need to fetch the PR to get current title/description
				existing_pr = self.get_existing_pr(head_branch)
				if existing_pr is None:
					msg = f"No PR found for branch {head_branch} with number {pr_number}"
					raise GitError(msg)

		else:
			# Look for existing PR for this branch
			existing_pr = self.get_existing_pr(head_branch)
			if existing_pr is not None:
				pr_number = existing_pr.number

		# Generate content if not provided
		if title is None or description is None:
			content = self.generate_content_from_commits(base_branch, head_branch, use_llm)
			if title is None:
				title = content["title"]
			if description is None:
				description = content["description"]

		# Create or update PR
		if pr_number is not None:
			# Update existing PR
			return self.update_pr(pr_number, title, description)
		# Create new PR
		return self.create_pr(base_branch, head_branch, title, description)

__init__

__init__(repo_path: Path, llm_client: LLMClient) -> None

Initialize the PR generator.

Parameters:

Name	Type	Description	Default
repo_path	Path	Path to the git repository	required
llm_client	LLMClient	LLMClient instance to use for content generation	required

Source code in src/codemap/git/pr_generator/generator.py

def __init__(
	self,
	repo_path: Path,
	llm_client: LLMClient,
) -> None:
	"""
	Initialize the PR generator.

	Args:
	    repo_path: Path to the git repository
	    llm_client: LLMClient instance to use for content generation

	"""
	self.repo_path = repo_path
	self.client = llm_client

repo_path instance-attribute

repo_path = repo_path

client instance-attribute

client = llm_client

generate_content_from_commits

generate_content_from_commits(
	base_branch: str, head_branch: str, use_llm: bool = True
) -> PRContent

Generate PR content (title and description) from commits.

Parameters:

Name	Type	Description	Default
base_branch	str	Base branch (e.g., main)	required
head_branch	str	Head branch (e.g., feature-branch)	required
use_llm	bool	Whether to use LLM for generation	True

Returns:

Type	Description
PRContent	Dictionary with 'title' and 'description' keys

Source code in src/codemap/git/pr_generator/generator.py

def generate_content_from_commits(self, base_branch: str, head_branch: str, use_llm: bool = True) -> PRContent:
	"""
	Generate PR content (title and description) from commits.

	Args:
	    base_branch: Base branch (e.g., main)
	    head_branch: Head branch (e.g., feature-branch)
	    use_llm: Whether to use LLM for generation

	Returns:
	    Dictionary with 'title' and 'description' keys

	"""
	# Get commit messages between branches
	commits = get_commit_messages(base_branch, head_branch)

	if not commits:
		return {"title": "Update branch", "description": "No changes in this PR."}

	if use_llm:
		# Generate title and description using LLM
		title = generate_pr_title_with_llm(commits, self.client)
		description = generate_pr_description_with_llm(commits, self.client)
	else:
		# Generate title and description using rule-based approach
		title = generate_pr_title_from_commits(commits)
		description = generate_pr_description_from_commits(commits)

	return {"title": title, "description": description}

generate_content_from_template

generate_content_from_template(
	branch_name: str,
	description: str,
	workflow_strategy: str = "github-flow",
) -> PRContent

Generate PR content (title and description) from a template.

Parameters:

Name	Type	Description	Default
branch_name	str	Name of the branch	required
description	str	Short description of the changes	required
workflow_strategy	str	Git workflow strategy to use	'github-flow'

Returns:

Type	Description
PRContent	Dictionary with 'title' and 'description' keys

Source code in src/codemap/git/pr_generator/generator.py

def generate_content_from_template(
	self, branch_name: str, description: str, workflow_strategy: str = "github-flow"
) -> PRContent:
	"""
	Generate PR content (title and description) from a template.

	Args:
	    branch_name: Name of the branch
	    description: Short description of the changes
	    workflow_strategy: Git workflow strategy to use

	Returns:
	    Dictionary with 'title' and 'description' keys

	"""
	return generate_pr_content_from_template(branch_name, description, workflow_strategy)

suggest_branch_name

suggest_branch_name(
	description: str, workflow_strategy: str = "github-flow"
) -> str

Suggest a branch name based on a description.

Parameters:

Name	Type	Description	Default
description	str	Description of the branch	required
workflow_strategy	str	Git workflow strategy to use	'github-flow'

Returns:

Type	Description
str	Suggested branch name

Source code in src/codemap/git/pr_generator/generator.py

def suggest_branch_name(self, description: str, workflow_strategy: str = "github-flow") -> str:
	"""
	Suggest a branch name based on a description.

	Args:
	    description: Description of the branch
	    workflow_strategy: Git workflow strategy to use

	Returns:
	    Suggested branch name

	"""
	return suggest_branch_name(description, workflow_strategy)

create_pr

create_pr(
	base_branch: str,
	head_branch: str,
	title: str,
	description: str,
) -> PullRequest

Create a pull request on GitHub.

Parameters:

Name	Type	Description	Default
base_branch	str	Base branch (e.g., main)	required
head_branch	str	Head branch (e.g., feature-branch)	required
title	str	PR title	required
description	str	PR description	required

Returns:

Type	Description
PullRequest	PullRequest object with PR details

Raises:

Type	Description
GitError	If PR creation fails

Source code in src/codemap/git/pr_generator/generator.py

def create_pr(self, base_branch: str, head_branch: str, title: str, description: str) -> PullRequest:
	"""
	Create a pull request on GitHub.

	Args:
	    base_branch: Base branch (e.g., main)
	    head_branch: Head branch (e.g., feature-branch)
	    title: PR title
	    description: PR description

	Returns:
	    PullRequest object with PR details

	Raises:
	    GitError: If PR creation fails

	"""
	return create_pull_request(base_branch, head_branch, title, description)

update_pr

update_pr(
	pr_number: int, title: str, description: str
) -> PullRequest

Update an existing pull request.

Parameters:

Name	Type	Description	Default
pr_number	int	PR number	required
title	str	New PR title	required
description	str	New PR description	required

Returns:

Type	Description
PullRequest	Updated PullRequest object

Raises:

Type	Description
GitError	If PR update fails

Source code in src/codemap/git/pr_generator/generator.py

def update_pr(self, pr_number: int, title: str, description: str) -> PullRequest:
	"""
	Update an existing pull request.

	Args:
	    pr_number: PR number
	    title: New PR title
	    description: New PR description

	Returns:
	    Updated PullRequest object

	Raises:
	    GitError: If PR update fails

	"""
	return update_pull_request(pr_number, title, description)

get_existing_pr

get_existing_pr(branch_name: str) -> PullRequest | None

Get an existing PR for a branch.

Parameters:

Name	Type	Description	Default
branch_name	str	Branch name	required

Returns:

Type	Description
PullRequest | None	PullRequest object if found, None otherwise

Source code in src/codemap/git/pr_generator/generator.py

def get_existing_pr(self, branch_name: str) -> PullRequest | None:
	"""
	Get an existing PR for a branch.

	Args:
	    branch_name: Branch name

	Returns:
	    PullRequest object if found, None otherwise

	"""
	return get_existing_pr(branch_name)

create_or_update_pr

create_or_update_pr(
	base_branch: str | None = None,
	head_branch: str | None = None,
	title: str | None = None,
	description: str | None = None,
	use_llm: bool = True,
	pr_number: int | None = None,
) -> PullRequest

Create a new PR or update an existing one.

Parameters:

Name	Type	Description	Default
base_branch	str | None	Base branch (defaults to default branch)	None
head_branch	str | None	Head branch	None
title	str | None	PR title (if None, will be generated)	None
description	str | None	PR description (if None, will be generated)	None
use_llm	bool	Whether to use LLM for content generation	True
pr_number	int | None	PR number for update (if None, will create new PR)	None

Returns:

Type	Description
PullRequest	PullRequest object

Raises:

Type	Description
GitError	If PR creation/update fails

Source code in src/codemap/git/pr_generator/generator.py

def create_or_update_pr(
	self,
	base_branch: str | None = None,
	head_branch: str | None = None,
	title: str | None = None,
	description: str | None = None,
	use_llm: bool = True,
	pr_number: int | None = None,
) -> PullRequest:
	"""
	Create a new PR or update an existing one.

	Args:
	    base_branch: Base branch (defaults to default branch)
	    head_branch: Head branch
	    title: PR title (if None, will be generated)
	    description: PR description (if None, will be generated)
	    use_llm: Whether to use LLM for content generation
	    pr_number: PR number for update (if None, will create new PR)

	Returns:
	    PullRequest object

	Raises:
	    GitError: If PR creation/update fails

	"""
	# Get default branch if base_branch is not specified
	if base_branch is None:
		base_branch = get_default_branch()

	# Set default head_branch to current branch if not specified
	if head_branch is None:
		try:
			from codemap.git.pr_generator.utils import get_current_branch

			head_branch = get_current_branch()
		except GitError as err:
			msg = "Failed to determine current branch"
			raise GitError(msg) from err

	# Check if PR exists
	existing_pr = None
	if pr_number is not None:
		# Updating an existing PR by number
		if title is None or description is None:
			# Need to fetch the PR to get current title/description
			existing_pr = self.get_existing_pr(head_branch)
			if existing_pr is None:
				msg = f"No PR found for branch {head_branch} with number {pr_number}"
				raise GitError(msg)

	else:
		# Look for existing PR for this branch
		existing_pr = self.get_existing_pr(head_branch)
		if existing_pr is not None:
			pr_number = existing_pr.number

	# Generate content if not provided
	if title is None or description is None:
		content = self.generate_content_from_commits(base_branch, head_branch, use_llm)
		if title is None:
			title = content["title"]
		if description is None:
			description = content["description"]

	# Create or update PR
	if pr_number is not None:
		# Update existing PR
		return self.update_pr(pr_number, title, description)
	# Create new PR
	return self.create_pr(base_branch, head_branch, title, description)

PR_DESCRIPTION_PROMPT module-attribute

PR_DESCRIPTION_PROMPT = "\nBased on the following commits, generate a comprehensive PR description following this template:\n\n## What type of PR is this? (check all applicable)\n\n- [ ] Refactor\n- [ ] Feature\n- [ ] Bug Fix\n- [ ] Optimization\n- [ ] Documentation Update\n\n## Description\n[Fill this section with a detailed description of the changes]\n\n## Related Tickets & Documents\n- Related Issue #\n- Closes #\n\n## Added/updated tests?\n- [ ] Yes\n- [ ] No, and this is why: [explanation]\n- [ ] I need help with writing tests\n\nConsider the following guidelines:\n- Check the appropriate PR type boxes based on the commit messages\n- Provide a clear, detailed description of the changes\n- Include any relevant issue numbers that this PR relates to or closes\n- Indicate if tests were added, and if not, explain why\n- Use bullet points for clarity\n\nCommits:\n{commit_list}\n\nPR Description:\n---\n\nIMPORTANT:\n- Do not include any other text in your response except the PR description.\n- Do not wrap the PR description in quotes.\n- Do not add any explanations or other text to your response.\n"

PR_TITLE_PROMPT module-attribute

PR_TITLE_PROMPT = 'Based on the following commits, generate a clear, concise PR title that captures the\nessence of the changes.\nFollow these guidelines:\n- Focus on the most important change\n- If there are multiple related changes, summarize them\n- Keep it under 80 characters\n- Start with a capital letter\n- Don\'t use a period at the end\n- Use present tense (e.g., "Add feature" not "Added feature")\n- Be descriptive and specific (e.g., "Fix memory leak in data processing" not just "Fix bug")\n- Include the type of change if clear (Feature, Fix, Refactor, etc.)\n\nCommits:\n{commit_list}\n\nPR Title:\n---\n\nIMPORTANT:\n- Do not include any other text in your response except the PR title.\n- Do not wrap the PR title in quotes.\n- Do not add any explanations or other text to your response.\n'

format_commits_for_prompt

format_commits_for_prompt(commits: list[str]) -> str

Format commit messages as a bulleted list.

Parameters:

Name	Type	Description	Default
commits	list[str]	List of commit messages	required

Returns:

Type	Description
str	Formatted commit list as a string

Source code in src/codemap/git/pr_generator/prompts.py

def format_commits_for_prompt(commits: list[str]) -> str:
	"""
	Format commit messages as a bulleted list.

	Args:
	    commits: List of commit messages

	Returns:
	    Formatted commit list as a string

	"""
	return "\n".join([f"- {commit}" for commit in commits])

BranchType module-attribute

BranchType = Literal[
	"feature", "release", "hotfix", "bugfix", "docs"
]

PRContent

Bases: TypedDict

Pull request content type.

Source code in src/codemap/git/pr_generator/schemas.py

class PRContent(TypedDict):
	"""Pull request content type."""

	title: str
	description: str

title instance-attribute

title: str

description instance-attribute

description: str

PullRequest dataclass

Represents a GitHub Pull Request.

Source code in src/codemap/git/pr_generator/schemas.py

@dataclass
class PullRequest:
	"""Represents a GitHub Pull Request."""

	branch: str
	title: str
	description: str
	url: str | None = None
	number: int | None = None

branch instance-attribute

branch: str

title instance-attribute

title: str

description instance-attribute

description: str

url class-attribute instance-attribute

url: str | None = None

number class-attribute instance-attribute

number: int | None = None

__init__

__init__(
	branch: str,
	title: str,
	description: str,
	url: str | None = None,
	number: int | None = None,
) -> None

WorkflowStrategySchema module-attribute

WorkflowStrategySchema = Literal[
	"github-flow", "gitflow", "trunk-based"
]

GitFlowStrategy

Bases: WorkflowStrategy

Implementation of GitFlow workflow strategy.

Source code in src/codemap/git/pr_generator/strategies.py

class GitFlowStrategy(WorkflowStrategy):
	"""Implementation of GitFlow workflow strategy."""

	def get_default_base(self, branch_type: str) -> str | None:
		"""
		Get the default base branch for GitFlow.

		Args:
		    branch_type: Type of branch (feature, release, hotfix, bugfix)

		Returns:
		    Name of the default base branch

		"""
		mapping = {
			"feature": "develop",
			"release": "main",
			"hotfix": "main",
			"bugfix": "develop",
		}
		default = get_default_branch()
		return mapping.get(branch_type, default)

	def get_branch_prefix(self, branch_type: str) -> str:
		"""
		Get the branch name prefix for GitFlow.

		Args:
		    branch_type: Type of branch (feature, release, hotfix, etc.)

		Returns:
		    Branch name prefix

		"""
		mapping = {
			"feature": "feature/",
			"release": "release/",
			"hotfix": "hotfix/",
			"bugfix": "bugfix/",
		}
		return mapping.get(branch_type, "")

	def get_branch_types(self) -> list[str]:
		"""
		Get valid branch types for GitFlow.

		Returns:
		    List of valid branch types for GitFlow

		"""
		return ["feature", "release", "hotfix", "bugfix"]

	def suggest_branch_name(self, branch_type: str, description: str) -> str:
		"""
		Suggest a branch name based on GitFlow conventions.

		Args:
		    branch_type: Type of branch (feature, release, hotfix, etc.)
		    description: Description of the branch

		Returns:
		    Suggested branch name

		"""
		prefix = self.get_branch_prefix(branch_type)

		if branch_type == "release":
			# Extract version number from description if it looks like a version
			version_match = re.search(r"(\d+\.\d+\.\d+)", description)
			if version_match:
				return f"{prefix}{version_match.group(1)}"

		# For other branch types, use the default implementation
		return super().suggest_branch_name(branch_type, description)

	def get_pr_templates(self, branch_type: str) -> dict[str, str]:
		"""
		Get PR title and description templates for GitFlow.

		Args:
		    branch_type: Type of branch (feature, release, hotfix, bugfix)

		Returns:
		    Dictionary with 'title' and 'description' templates

		"""
		return GITFLOW_PR_TEMPLATES.get(branch_type, DEFAULT_PR_TEMPLATE)

get_default_base

get_default_base(branch_type: str) -> str | None

Get the default base branch for GitFlow.

Parameters:

Name	Type	Description	Default
branch_type	str	Type of branch (feature, release, hotfix, bugfix)	required

Returns:

Type	Description
str | None	Name of the default base branch

Source code in src/codemap/git/pr_generator/strategies.py

def get_default_base(self, branch_type: str) -> str | None:
	"""
	Get the default base branch for GitFlow.

	Args:
	    branch_type: Type of branch (feature, release, hotfix, bugfix)

	Returns:
	    Name of the default base branch

	"""
	mapping = {
		"feature": "develop",
		"release": "main",
		"hotfix": "main",
		"bugfix": "develop",
	}
	default = get_default_branch()
	return mapping.get(branch_type, default)

get_branch_prefix

get_branch_prefix(branch_type: str) -> str

Get the branch name prefix for GitFlow.

Parameters:

Name	Type	Description	Default
branch_type	str	Type of branch (feature, release, hotfix, etc.)	required

Returns:

Type	Description
str	Branch name prefix

Source code in src/codemap/git/pr_generator/strategies.py

def get_branch_prefix(self, branch_type: str) -> str:
	"""
	Get the branch name prefix for GitFlow.

	Args:
	    branch_type: Type of branch (feature, release, hotfix, etc.)

	Returns:
	    Branch name prefix

	"""
	mapping = {
		"feature": "feature/",
		"release": "release/",
		"hotfix": "hotfix/",
		"bugfix": "bugfix/",
	}
	return mapping.get(branch_type, "")

get_branch_types

get_branch_types() -> list[str]

Get valid branch types for GitFlow.

Returns:

Type	Description
list[str]	List of valid branch types for GitFlow

Source code in src/codemap/git/pr_generator/strategies.py

def get_branch_types(self) -> list[str]:
	"""
	Get valid branch types for GitFlow.

	Returns:
	    List of valid branch types for GitFlow

	"""
	return ["feature", "release", "hotfix", "bugfix"]

suggest_branch_name

suggest_branch_name(
	branch_type: str, description: str
) -> str

Suggest a branch name based on GitFlow conventions.

Parameters:

Name	Type	Description	Default
branch_type	str	Type of branch (feature, release, hotfix, etc.)	required
description	str	Description of the branch	required

Returns:

Type	Description
str	Suggested branch name

Source code in src/codemap/git/pr_generator/strategies.py

def suggest_branch_name(self, branch_type: str, description: str) -> str:
	"""
	Suggest a branch name based on GitFlow conventions.

	Args:
	    branch_type: Type of branch (feature, release, hotfix, etc.)
	    description: Description of the branch

	Returns:
	    Suggested branch name

	"""
	prefix = self.get_branch_prefix(branch_type)

	if branch_type == "release":
		# Extract version number from description if it looks like a version
		version_match = re.search(r"(\d+\.\d+\.\d+)", description)
		if version_match:
			return f"{prefix}{version_match.group(1)}"

	# For other branch types, use the default implementation
	return super().suggest_branch_name(branch_type, description)

get_pr_templates

get_pr_templates(branch_type: str) -> dict[str, str]

Get PR title and description templates for GitFlow.

Parameters:

Name	Type	Description	Default
branch_type	str	Type of branch (feature, release, hotfix, bugfix)	required

Returns:

Type	Description
dict[str, str]	Dictionary with 'title' and 'description' templates

Source code in src/codemap/git/pr_generator/strategies.py

def get_pr_templates(self, branch_type: str) -> dict[str, str]:
	"""
	Get PR title and description templates for GitFlow.

	Args:
	    branch_type: Type of branch (feature, release, hotfix, bugfix)

	Returns:
	    Dictionary with 'title' and 'description' templates

	"""
	return GITFLOW_PR_TEMPLATES.get(branch_type, DEFAULT_PR_TEMPLATE)

GitHubFlowStrategy

Bases: WorkflowStrategy

Implementation of GitHub Flow workflow strategy.

Source code in src/codemap/git/pr_generator/strategies.py

class GitHubFlowStrategy(WorkflowStrategy):
	"""Implementation of GitHub Flow workflow strategy."""

	def get_default_base(self, branch_type: str) -> str | None:  # noqa: ARG002
		"""
		Get the default base branch for GitHub Flow.

		Args:
		    branch_type: Type of branch (always 'feature' in GitHub Flow)

		Returns:
		    Name of the default base branch (usually 'main')

		"""
		# Ignoring branch_type as GitHub Flow always uses the default branch
		return get_default_branch()

	def get_branch_prefix(self, branch_type: str) -> str:  # noqa: ARG002
		"""
		Get the branch name prefix for GitHub Flow.

		Args:
		    branch_type: Type of branch (always 'feature' in GitHub Flow)

		Returns:
		    Branch name prefix (empty string for GitHub Flow)

		"""
		# Ignoring branch_type as GitHub Flow doesn't use prefixes
		return ""

	def get_branch_types(self) -> list[str]:
		"""
		Get valid branch types for GitHub Flow.

		Returns:
		    List containing only 'feature'

		"""
		return ["feature"]

	def get_pr_templates(self, branch_type: str) -> dict[str, str]:  # noqa: ARG002
		"""
		Get PR title and description templates for GitHub Flow.

		Args:
		    branch_type: Type of branch (always 'feature' in GitHub Flow)

		Returns:
		    Dictionary with 'title' and 'description' templates

		"""
		return GITHUB_FLOW_PR_TEMPLATE

get_default_base

get_default_base(branch_type: str) -> str | None

Get the default base branch for GitHub Flow.

Parameters:

Name	Type	Description	Default
branch_type	str	Type of branch (always 'feature' in GitHub Flow)	required

Returns:

Type	Description
str | None	Name of the default base branch (usually 'main')

Source code in src/codemap/git/pr_generator/strategies.py

def get_default_base(self, branch_type: str) -> str | None:  # noqa: ARG002
	"""
	Get the default base branch for GitHub Flow.

	Args:
	    branch_type: Type of branch (always 'feature' in GitHub Flow)

	Returns:
	    Name of the default base branch (usually 'main')

	"""
	# Ignoring branch_type as GitHub Flow always uses the default branch
	return get_default_branch()

get_branch_prefix

get_branch_prefix(branch_type: str) -> str

Get the branch name prefix for GitHub Flow.

Parameters:

Name	Type	Description	Default
branch_type	str	Type of branch (always 'feature' in GitHub Flow)	required

Returns:

Type	Description
str	Branch name prefix (empty string for GitHub Flow)

Source code in src/codemap/git/pr_generator/strategies.py

def get_branch_prefix(self, branch_type: str) -> str:  # noqa: ARG002
	"""
	Get the branch name prefix for GitHub Flow.

	Args:
	    branch_type: Type of branch (always 'feature' in GitHub Flow)

	Returns:
	    Branch name prefix (empty string for GitHub Flow)

	"""
	# Ignoring branch_type as GitHub Flow doesn't use prefixes
	return ""

get_branch_types

get_branch_types() -> list[str]

Get valid branch types for GitHub Flow.

Returns:

Type	Description
list[str]	List containing only 'feature'

Source code in src/codemap/git/pr_generator/strategies.py

def get_branch_types(self) -> list[str]:
	"""
	Get valid branch types for GitHub Flow.

	Returns:
	    List containing only 'feature'

	"""
	return ["feature"]

get_pr_templates

get_pr_templates(branch_type: str) -> dict[str, str]

Get PR title and description templates for GitHub Flow.

Parameters:

Name	Type	Description	Default
branch_type	str	Type of branch (always 'feature' in GitHub Flow)	required

Returns:

Type	Description
dict[str, str]	Dictionary with 'title' and 'description' templates

Source code in src/codemap/git/pr_generator/strategies.py

def get_pr_templates(self, branch_type: str) -> dict[str, str]:  # noqa: ARG002
	"""
	Get PR title and description templates for GitHub Flow.

	Args:
	    branch_type: Type of branch (always 'feature' in GitHub Flow)

	Returns:
	    Dictionary with 'title' and 'description' templates

	"""
	return GITHUB_FLOW_PR_TEMPLATE

TrunkBasedStrategy

Bases: WorkflowStrategy

Implementation of Trunk-Based Development workflow strategy.

Source code in src/codemap/git/pr_generator/strategies.py

class TrunkBasedStrategy(WorkflowStrategy):
	"""Implementation of Trunk-Based Development workflow strategy."""

	def get_default_base(self, branch_type: str) -> str | None:  # noqa: ARG002
		"""
		Get the default base branch for Trunk-Based Development.

		Args:
		    branch_type: Type of branch

		Returns:
		    Name of the default base branch (trunk, which is usually 'main')

		"""
		# Ignoring branch_type as Trunk-Based Development always uses the main branch
		return get_default_branch()

	def get_branch_prefix(self, branch_type: str) -> str:
		"""
		Get the branch name prefix for Trunk-Based Development.

		Args:
		    branch_type: Type of branch

		Returns:
		    Branch name prefix

		"""
		return "fb/" if branch_type == "feature" else ""

	def get_branch_types(self) -> list[str]:
		"""
		Get valid branch types for Trunk-Based Development.

		Returns:
		    List containing only 'feature'

		"""
		return ["feature"]

	def suggest_branch_name(self, branch_type: str, description: str) -> str:
		"""
		Suggest a branch name based on Trunk-Based Development conventions.

		Emphasizes short-lived, descriptive branches.

		Args:
		    branch_type: Type of branch
		    description: Description of the branch

		Returns:
		    Suggested branch name

		"""
		# For trunk-based development, try to generate very short names
		words = description.split()
		# Filter out common words like "implement", "the", "and", etc.
		common_words = ["the", "and", "for", "with", "implement", "implementing", "implementation"]
		words = [w for w in words if len(w) > MIN_SIGNIFICANT_WORD_LENGTH and w.lower() not in common_words]

		# Take up to 3 significant words
		short_desc = "-".join(words[:3]).lower()
		short_desc = re.sub(r"[^a-zA-Z0-9-]", "-", short_desc)
		short_desc = re.sub(r"-+", "-", short_desc)
		short_desc = short_desc.strip("-")

		# Add username prefix for trunk-based (optional)
		try:
			username = run_git_command(["git", "config", "user.name"]).strip().split()[0].lower()
			username = re.sub(r"[^a-zA-Z0-9]", "", username)
			return f"{username}/{short_desc}"
		except (GitError, IndexError):
			# Fall back to standard prefix if username not available
			prefix = self.get_branch_prefix(branch_type)
			return f"{prefix}{short_desc}"

	def get_pr_templates(self, branch_type: str) -> dict[str, str]:  # noqa: ARG002
		"""
		Get PR title and description templates for Trunk-Based Development.

		Args:
		    branch_type: Type of branch

		Returns:
		    Dictionary with 'title' and 'description' templates

		"""
		return TRUNK_BASED_PR_TEMPLATE

get_default_base

get_default_base(branch_type: str) -> str | None

Get the default base branch for Trunk-Based Development.

Parameters:

Name	Type	Description	Default
branch_type	str	Type of branch	required

Returns:

Type	Description
str | None	Name of the default base branch (trunk, which is usually 'main')

Source code in src/codemap/git/pr_generator/strategies.py

def get_default_base(self, branch_type: str) -> str | None:  # noqa: ARG002
	"""
	Get the default base branch for Trunk-Based Development.

	Args:
	    branch_type: Type of branch

	Returns:
	    Name of the default base branch (trunk, which is usually 'main')

	"""
	# Ignoring branch_type as Trunk-Based Development always uses the main branch
	return get_default_branch()

get_branch_prefix

get_branch_prefix(branch_type: str) -> str

Get the branch name prefix for Trunk-Based Development.

Parameters:

Name	Type	Description	Default
branch_type	str	Type of branch	required

Returns:

Type	Description
str	Branch name prefix

Source code in src/codemap/git/pr_generator/strategies.py

def get_branch_prefix(self, branch_type: str) -> str:
	"""
	Get the branch name prefix for Trunk-Based Development.

	Args:
	    branch_type: Type of branch

	Returns:
	    Branch name prefix

	"""
	return "fb/" if branch_type == "feature" else ""

get_branch_types

get_branch_types() -> list[str]

Get valid branch types for Trunk-Based Development.

Returns:

Type	Description
list[str]	List containing only 'feature'

Source code in src/codemap/git/pr_generator/strategies.py

def get_branch_types(self) -> list[str]:
	"""
	Get valid branch types for Trunk-Based Development.

	Returns:
	    List containing only 'feature'

	"""
	return ["feature"]

suggest_branch_name

suggest_branch_name(
	branch_type: str, description: str
) -> str

Suggest a branch name based on Trunk-Based Development conventions.

Emphasizes short-lived, descriptive branches.

Parameters:

Name	Type	Description	Default
branch_type	str	Type of branch	required
description	str	Description of the branch	required

Returns:

Type	Description
str	Suggested branch name

Source code in src/codemap/git/pr_generator/strategies.py

def suggest_branch_name(self, branch_type: str, description: str) -> str:
	"""
	Suggest a branch name based on Trunk-Based Development conventions.

	Emphasizes short-lived, descriptive branches.

	Args:
	    branch_type: Type of branch
	    description: Description of the branch

	Returns:
	    Suggested branch name

	"""
	# For trunk-based development, try to generate very short names
	words = description.split()
	# Filter out common words like "implement", "the", "and", etc.
	common_words = ["the", "and", "for", "with", "implement", "implementing", "implementation"]
	words = [w for w in words if len(w) > MIN_SIGNIFICANT_WORD_LENGTH and w.lower() not in common_words]

	# Take up to 3 significant words
	short_desc = "-".join(words[:3]).lower()
	short_desc = re.sub(r"[^a-zA-Z0-9-]", "-", short_desc)
	short_desc = re.sub(r"-+", "-", short_desc)
	short_desc = short_desc.strip("-")

	# Add username prefix for trunk-based (optional)
	try:
		username = run_git_command(["git", "config", "user.name"]).strip().split()[0].lower()
		username = re.sub(r"[^a-zA-Z0-9]", "", username)
		return f"{username}/{short_desc}"
	except (GitError, IndexError):
		# Fall back to standard prefix if username not available
		prefix = self.get_branch_prefix(branch_type)
		return f"{prefix}{short_desc}"

get_pr_templates

get_pr_templates(branch_type: str) -> dict[str, str]

Get PR title and description templates for Trunk-Based Development.

Parameters:

Name	Type	Description	Default
branch_type	str	Type of branch	required

Returns:

Type	Description
dict[str, str]	Dictionary with 'title' and 'description' templates

Source code in src/codemap/git/pr_generator/strategies.py

def get_pr_templates(self, branch_type: str) -> dict[str, str]:  # noqa: ARG002
	"""
	Get PR title and description templates for Trunk-Based Development.

	Args:
	    branch_type: Type of branch

	Returns:
	    Dictionary with 'title' and 'description' templates

	"""
	return TRUNK_BASED_PR_TEMPLATE

WorkflowStrategy

Bases: ABC

Base class for git workflow strategies.

Source code in src/codemap/git/pr_generator/strategies.py

class WorkflowStrategy(ABC):
	"""Base class for git workflow strategies."""

	@abstractmethod
	def get_default_base(self, branch_type: str) -> str | None:
		"""
		Get the default base branch for a given branch type.

		Args:
		    branch_type: Type of branch (feature, release, hotfix, etc.)

		Returns:
		    Name of the default base branch

		"""
		raise NotImplementedError

	def suggest_branch_name(self, branch_type: str, description: str) -> str:
		"""
		Suggest a branch name based on the workflow.

		Args:
		    branch_type: Type of branch (feature, release, hotfix, etc.)
		    description: Description of the branch

		Returns:
		    Suggested branch name

		"""
		# Default implementation
		clean_description = re.sub(r"[^a-zA-Z0-9]+", "-", description.lower())
		clean_description = clean_description.strip("-")
		prefix = self.get_branch_prefix(branch_type)
		return f"{prefix}{clean_description}"

	@abstractmethod
	def get_branch_prefix(self, branch_type: str) -> str:
		"""
		Get the branch name prefix for a given branch type.

		Args:
		    branch_type: Type of branch (feature, release, hotfix, etc.)

		Returns:
		    Branch name prefix

		"""
		raise NotImplementedError

	@abstractmethod
	def get_branch_types(self) -> list[str]:
		"""
		Get valid branch types for this workflow.

		Returns:
		    List of valid branch types

		"""
		raise NotImplementedError

	def detect_branch_type(self, branch_name: str | None) -> str | None:
		"""
		Detect the type of a branch from its name.

		Args:
		    branch_name: Name of the branch

		Returns:
		    Branch type or None if not detected

		"""
		for branch_type in self.get_branch_types():
			prefix = self.get_branch_prefix(branch_type)
			if branch_name and branch_name.startswith(prefix):
				return branch_type
		return None

	def get_pr_templates(self, branch_type: str) -> dict[str, str]:  # noqa: ARG002
		"""
		Get PR title and description templates for a given branch type.

		Args:
		    branch_type: Type of branch (feature, release, hotfix, etc.)

		Returns:
		    Dictionary with 'title' and 'description' templates

		"""
		# Return the default templates
		return DEFAULT_PR_TEMPLATE

	def get_remote_branches(self) -> list[str]:
		"""
		Get list of remote branches.

		Returns:
		    List of remote branch names (without 'origin/' prefix)

		"""
		try:
			branches = run_git_command(["git", "branch", "-r"]).strip().split("\n")
			# Clean up branch names and remove 'origin/' prefix
			remote_branches = []
			for branch_name in branches:
				branch_clean = branch_name.strip()
				if branch_clean.startswith("origin/"):
					branch_name_without_prefix = branch_clean[7:]  # Remove 'origin/' prefix
					# Exclude HEAD branches
					if not branch_name_without_prefix.startswith("HEAD"):
						remote_branches.append(branch_name_without_prefix)
			return remote_branches
		except GitError:
			return []

	def get_local_branches(self) -> list[str]:
		"""
		Get list of local branches.

		Returns:
		    List of local branch names

		"""
		try:
			branches = run_git_command(["git", "branch"]).strip().split("\n")
			# Clean up branch names and remove the '*' from current branch
			local_branches = []
			for branch_name in branches:
				branch_clean = branch_name.strip().removeprefix("* ")  # Remove '* ' prefix
				local_branches.append(branch_clean)
			return local_branches
		except GitError:
			return []

	def get_branches_by_type(self) -> dict[str, list[str]]:
		"""
		Group branches by their type.

		Returns:
		    Dictionary mapping branch types to lists of branch names

		"""
		result = {branch_type: [] for branch_type in self.get_branch_types()}
		result["other"] = []  # For branches that don't match any type

		# Get all branches (local and remote)
		all_branches = set(self.get_local_branches() + self.get_remote_branches())

		for branch in all_branches:
			branch_type = self.detect_branch_type(branch)
			if branch_type:
				result[branch_type].append(branch)
			else:
				result["other"].append(branch)

		return result

	def get_branch_metadata(self, branch_name: str) -> dict[str, Any]:
		"""
		Get metadata for a specific branch.

		Args:
		    branch_name: Name of the branch

		Returns:
		    Dictionary with branch metadata

		"""
		try:
			# Get last commit date
			date_cmd = [
				"git",
				"log",
				"-1",
				"--format=%ad",
				"--date=relative",
				branch_name if branch_exists(branch_name) else f"origin/{branch_name}",
			]
			date = run_git_command(date_cmd).strip()

			# Get commit count (compared to default branch)
			default = get_default_branch()
			count_cmd = ["git", "rev-list", "--count", f"{default}..{branch_name}"]
			try:
				count = run_git_command(count_cmd).strip()
			except GitError:
				count = "0"

			# Detect branch type
			branch_type = self.detect_branch_type(branch_name)

			return {
				"last_commit_date": date,
				"commit_count": count,
				"branch_type": branch_type,
				"is_local": branch_name in self.get_local_branches(),
				"is_remote": branch_name in self.get_remote_branches(),
			}
		except GitError:
			# Return default metadata if there's an error
			return {
				"last_commit_date": "unknown",
				"commit_count": "0",
				"branch_type": self.detect_branch_type(branch_name),
				"is_local": False,
				"is_remote": False,
			}

	def get_all_branches_with_metadata(self) -> dict[str, dict[str, Any]]:
		"""
		Get all branches with metadata.

		Returns:
		    Dictionary mapping branch names to metadata dictionaries

		"""
		result = {}
		all_branches = set(self.get_local_branches() + self.get_remote_branches())

		for branch in all_branches:
			result[branch] = self.get_branch_metadata(branch)

		return result

get_default_base abstractmethod

get_default_base(branch_type: str) -> str | None

Get the default base branch for a given branch type.

Parameters:

Name	Type	Description	Default
branch_type	str	Type of branch (feature, release, hotfix, etc.)	required

Returns:

Type	Description
str | None	Name of the default base branch

Source code in src/codemap/git/pr_generator/strategies.py

@abstractmethod
def get_default_base(self, branch_type: str) -> str | None:
	"""
	Get the default base branch for a given branch type.

	Args:
	    branch_type: Type of branch (feature, release, hotfix, etc.)

	Returns:
	    Name of the default base branch

	"""
	raise NotImplementedError

suggest_branch_name

suggest_branch_name(
	branch_type: str, description: str
) -> str

Suggest a branch name based on the workflow.

Parameters:

Name	Type	Description	Default
branch_type	str	Type of branch (feature, release, hotfix, etc.)	required
description	str	Description of the branch	required

Returns:

Type	Description
str	Suggested branch name

Source code in src/codemap/git/pr_generator/strategies.py

def suggest_branch_name(self, branch_type: str, description: str) -> str:
	"""
	Suggest a branch name based on the workflow.

	Args:
	    branch_type: Type of branch (feature, release, hotfix, etc.)
	    description: Description of the branch

	Returns:
	    Suggested branch name

	"""
	# Default implementation
	clean_description = re.sub(r"[^a-zA-Z0-9]+", "-", description.lower())
	clean_description = clean_description.strip("-")
	prefix = self.get_branch_prefix(branch_type)
	return f"{prefix}{clean_description}"

get_branch_prefix abstractmethod

get_branch_prefix(branch_type: str) -> str

Get the branch name prefix for a given branch type.

Parameters:

Name	Type	Description	Default
branch_type	str	Type of branch (feature, release, hotfix, etc.)	required

Returns:

Type	Description
str	Branch name prefix

Source code in src/codemap/git/pr_generator/strategies.py

@abstractmethod
def get_branch_prefix(self, branch_type: str) -> str:
	"""
	Get the branch name prefix for a given branch type.

	Args:
	    branch_type: Type of branch (feature, release, hotfix, etc.)

	Returns:
	    Branch name prefix

	"""
	raise NotImplementedError

get_branch_types abstractmethod

get_branch_types() -> list[str]

Get valid branch types for this workflow.

Returns:

Type	Description
list[str]	List of valid branch types

Source code in src/codemap/git/pr_generator/strategies.py

@abstractmethod
def get_branch_types(self) -> list[str]:
	"""
	Get valid branch types for this workflow.

	Returns:
	    List of valid branch types

	"""
	raise NotImplementedError

detect_branch_type

detect_branch_type(branch_name: str | None) -> str | None

Detect the type of a branch from its name.

Parameters:

Name	Type	Description	Default
branch_name	str | None	Name of the branch	required

Returns:

Type	Description
str | None	Branch type or None if not detected

Source code in src/codemap/git/pr_generator/strategies.py

def detect_branch_type(self, branch_name: str | None) -> str | None:
	"""
	Detect the type of a branch from its name.

	Args:
	    branch_name: Name of the branch

	Returns:
	    Branch type or None if not detected

	"""
	for branch_type in self.get_branch_types():
		prefix = self.get_branch_prefix(branch_type)
		if branch_name and branch_name.startswith(prefix):
			return branch_type
	return None

get_pr_templates

get_pr_templates(branch_type: str) -> dict[str, str]

Get PR title and description templates for a given branch type.

Parameters:

Name	Type	Description	Default
branch_type	str	Type of branch (feature, release, hotfix, etc.)	required

Returns:

Type	Description
dict[str, str]	Dictionary with 'title' and 'description' templates

Source code in src/codemap/git/pr_generator/strategies.py

def get_pr_templates(self, branch_type: str) -> dict[str, str]:  # noqa: ARG002
	"""
	Get PR title and description templates for a given branch type.

	Args:
	    branch_type: Type of branch (feature, release, hotfix, etc.)

	Returns:
	    Dictionary with 'title' and 'description' templates

	"""
	# Return the default templates
	return DEFAULT_PR_TEMPLATE

get_remote_branches

get_remote_branches() -> list[str]

Get list of remote branches.

Returns:

Type	Description
list[str]	List of remote branch names (without 'origin/' prefix)

Source code in src/codemap/git/pr_generator/strategies.py

def get_remote_branches(self) -> list[str]:
	"""
	Get list of remote branches.

	Returns:
	    List of remote branch names (without 'origin/' prefix)

	"""
	try:
		branches = run_git_command(["git", "branch", "-r"]).strip().split("\n")
		# Clean up branch names and remove 'origin/' prefix
		remote_branches = []
		for branch_name in branches:
			branch_clean = branch_name.strip()
			if branch_clean.startswith("origin/"):
				branch_name_without_prefix = branch_clean[7:]  # Remove 'origin/' prefix
				# Exclude HEAD branches
				if not branch_name_without_prefix.startswith("HEAD"):
					remote_branches.append(branch_name_without_prefix)
		return remote_branches
	except GitError:
		return []

get_local_branches

get_local_branches() -> list[str]

Get list of local branches.

Returns:

Type	Description
list[str]	List of local branch names

Source code in src/codemap/git/pr_generator/strategies.py

def get_local_branches(self) -> list[str]:
	"""
	Get list of local branches.

	Returns:
	    List of local branch names

	"""
	try:
		branches = run_git_command(["git", "branch"]).strip().split("\n")
		# Clean up branch names and remove the '*' from current branch
		local_branches = []
		for branch_name in branches:
			branch_clean = branch_name.strip().removeprefix("* ")  # Remove '* ' prefix
			local_branches.append(branch_clean)
		return local_branches
	except GitError:
		return []

get_branches_by_type

get_branches_by_type() -> dict[str, list[str]]

Group branches by their type.

Returns:

Type	Description
dict[str, list[str]]	Dictionary mapping branch types to lists of branch names

Source code in src/codemap/git/pr_generator/strategies.py

def get_branches_by_type(self) -> dict[str, list[str]]:
	"""
	Group branches by their type.

	Returns:
	    Dictionary mapping branch types to lists of branch names

	"""
	result = {branch_type: [] for branch_type in self.get_branch_types()}
	result["other"] = []  # For branches that don't match any type

	# Get all branches (local and remote)
	all_branches = set(self.get_local_branches() + self.get_remote_branches())

	for branch in all_branches:
		branch_type = self.detect_branch_type(branch)
		if branch_type:
			result[branch_type].append(branch)
		else:
			result["other"].append(branch)

	return result

get_branch_metadata

get_branch_metadata(branch_name: str) -> dict[str, Any]

Get metadata for a specific branch.

Parameters:

Name	Type	Description	Default
branch_name	str	Name of the branch	required

Returns:

Type	Description
dict[str, Any]	Dictionary with branch metadata

Source code in src/codemap/git/pr_generator/strategies.py

def get_branch_metadata(self, branch_name: str) -> dict[str, Any]:
	"""
	Get metadata for a specific branch.

	Args:
	    branch_name: Name of the branch

	Returns:
	    Dictionary with branch metadata

	"""
	try:
		# Get last commit date
		date_cmd = [
			"git",
			"log",
			"-1",
			"--format=%ad",
			"--date=relative",
			branch_name if branch_exists(branch_name) else f"origin/{branch_name}",
		]
		date = run_git_command(date_cmd).strip()

		# Get commit count (compared to default branch)
		default = get_default_branch()
		count_cmd = ["git", "rev-list", "--count", f"{default}..{branch_name}"]
		try:
			count = run_git_command(count_cmd).strip()
		except GitError:
			count = "0"

		# Detect branch type
		branch_type = self.detect_branch_type(branch_name)

		return {
			"last_commit_date": date,
			"commit_count": count,
			"branch_type": branch_type,
			"is_local": branch_name in self.get_local_branches(),
			"is_remote": branch_name in self.get_remote_branches(),
		}
	except GitError:
		# Return default metadata if there's an error
		return {
			"last_commit_date": "unknown",
			"commit_count": "0",
			"branch_type": self.detect_branch_type(branch_name),
			"is_local": False,
			"is_remote": False,
		}

get_all_branches_with_metadata

get_all_branches_with_metadata() -> dict[
	str, dict[str, Any]
]

Get all branches with metadata.

Returns:

Type	Description
dict[str, dict[str, Any]]	Dictionary mapping branch names to metadata dictionaries

Source code in src/codemap/git/pr_generator/strategies.py

def get_all_branches_with_metadata(self) -> dict[str, dict[str, Any]]:
	"""
	Get all branches with metadata.

	Returns:
	    Dictionary mapping branch names to metadata dictionaries

	"""
	result = {}
	all_branches = set(self.get_local_branches() + self.get_remote_branches())

	for branch in all_branches:
		result[branch] = self.get_branch_metadata(branch)

	return result

create_strategy

create_strategy(strategy_name: str) -> WorkflowStrategy

Create a workflow strategy instance based on the strategy name.

Parameters:

Name	Type	Description	Default
strategy_name	str	The name of the workflow strategy to create.	required

Returns:

Type	Description
WorkflowStrategy	An instance of the requested workflow strategy.

Raises:

Type	Description
ValueError	If the strategy name is unknown.

Source code in src/codemap/git/pr_generator/strategies.py

def create_strategy(strategy_name: str) -> WorkflowStrategy:
	"""
	Create a workflow strategy instance based on the strategy name.

	Args:
	    strategy_name: The name of the workflow strategy to create.

	Returns:
	    An instance of the requested workflow strategy.

	Raises:
	    ValueError: If the strategy name is unknown.

	"""
	strategy_class = get_strategy_class(strategy_name)
	if not strategy_class:
		error_msg = f"Unknown workflow strategy: {strategy_name}"
		raise ValueError(error_msg)

	return strategy_class()

PRCreationError

Bases: GitError

Error raised when there's an issue creating or updating a pull request.

Source code in src/codemap/git/pr_generator/utils.py

class PRCreationError(GitError):
	"""Error raised when there's an issue creating or updating a pull request."""

checkout_branch

checkout_branch(branch_name: str) -> None

Checkout an existing branch.

Parameters:

Name	Type	Description	Default
branch_name	str	Name of the branch to checkout	required

Raises:

Type	Description
GitError	If git command fails

Source code in src/codemap/git/pr_generator/utils.py

def checkout_branch(branch_name: str) -> None:
	"""
	Checkout an existing branch.

	Args:
	    branch_name: Name of the branch to checkout

	Raises:
	    GitError: If git command fails

	"""
	try:
		run_git_command(["git", "checkout", branch_name])
	except GitError as e:
		msg = f"Failed to checkout branch: {branch_name}"
		raise GitError(msg) from e

create_branch

create_branch(branch_name: str) -> None

Create a new branch and switch to it.

Parameters:

Name	Type	Description	Default
branch_name	str	Name of the branch to create	required

Raises:

Type	Description
GitError	If git command fails

Source code in src/codemap/git/pr_generator/utils.py

def create_branch(branch_name: str) -> None:
	"""
	Create a new branch and switch to it.

	Args:
	    branch_name: Name of the branch to create

	Raises:
	    GitError: If git command fails

	"""
	try:
		run_git_command(["git", "checkout", "-b", branch_name])
	except GitError as e:
		msg = f"Failed to create branch: {branch_name}"
		raise GitError(msg) from e

create_pull_request

create_pull_request(
	base_branch: str,
	head_branch: str,
	title: str,
	description: str,
) -> PullRequest

Create a pull request on GitHub.

Parameters:

Name	Type	Description	Default
base_branch	str	Base branch (e.g., main)	required
head_branch	str	Head branch (e.g., feature-branch)	required
title	str	PR title	required
description	str	PR description	required

Returns:

Type	Description
PullRequest	PullRequest object with PR details

Raises:

Type	Description
PRCreationError	If PR creation fails

Source code in src/codemap/git/pr_generator/utils.py

def create_pull_request(base_branch: str, head_branch: str, title: str, description: str) -> PullRequest:
	"""
	Create a pull request on GitHub.

	Args:
	    base_branch: Base branch (e.g., main)
	    head_branch: Head branch (e.g., feature-branch)
	    title: PR title
	    description: PR description

	Returns:
	    PullRequest object with PR details

	Raises:
	    PRCreationError: If PR creation fails

	"""
	try:
		# Check if gh CLI is installed
		try:
			subprocess.run(["gh", "--version"], check=True, capture_output=True, text=True)  # noqa: S603, S607
		except (subprocess.CalledProcessError, FileNotFoundError) as e:
			msg = "GitHub CLI (gh) is not installed or not in PATH. Please install it to create PRs."
			raise PRCreationError(msg) from e

		# Create PR using GitHub CLI
		cmd = [
			"gh",
			"pr",
			"create",
			"--base",
			base_branch,
			"--head",
			head_branch,
			"--title",
			title,
			"--body",
			description,
		]

		logger.info(f"Attempting to create PR with command: {' '.join(cmd)}")
		logger.info(f"Arguments - Base: '{base_branch}', Head: '{head_branch}'")

		logger.debug("Running GitHub CLI command: %s", " ".join(cmd))
		result = subprocess.run(  # noqa: S603
			cmd,
			check=True,
			capture_output=True,
			text=True,
			encoding="utf-8",
		)

		# gh pr create outputs the URL of the created PR to stdout
		pr_url = result.stdout.strip()
		pr_number = None

		# Try to extract PR number from URL
		match = re.search(r"/pull/(\d+)$", pr_url)
		if match:
			pr_number = int(match.group(1))
		else:
			logger.warning("Could not extract PR number from URL: %s", pr_url)

		return PullRequest(
			branch=head_branch,
			title=title,
			description=description,
			url=pr_url,
			number=pr_number,
		)
	except subprocess.CalledProcessError as e:
		# Use stderr for the error message from gh
		error_message = e.stderr.strip() if e.stderr else "Unknown gh error"
		logger.exception("GitHub CLI error during PR creation: %s", error_message)
		msg = f"Failed to create PR: {error_message}"
		raise PRCreationError(msg) from e
	except (
		FileNotFoundError,
		json.JSONDecodeError,
	) as e:  # Keep JSONDecodeError in case gh output changes unexpectedly
		# Handle gh not found or unexpected output issues
		logger.exception("Error running gh command or parsing output: %s")
		msg = f"Error during PR creation: {e}"
		raise PRCreationError(msg) from e

detect_branch_type

detect_branch_type(
	branch_name: str, strategy_name: str = "github-flow"
) -> str

Detect the type of a branch based on its name and workflow strategy.

Parameters:

Name	Type	Description	Default
branch_name	str	Name of the branch	required
strategy_name	str	Name of the workflow strategy to use	'github-flow'

Returns:

Type	Description
str	Branch type or "feature" if not detected

Source code in src/codemap/git/pr_generator/utils.py

def detect_branch_type(branch_name: str, strategy_name: str = "github-flow") -> str:
	"""
	Detect the type of a branch based on its name and workflow strategy.

	Args:
	    branch_name: Name of the branch
	    strategy_name: Name of the workflow strategy to use

	Returns:
	    Branch type or "feature" if not detected

	"""
	strategy = create_strategy(strategy_name)
	# Handle None branch_name
	if not branch_name:
		return "feature"  # Default if branch name is None
	branch_type = strategy.detect_branch_type(branch_name)

	return branch_type or "feature"  # Default to feature if not detected

generate_pr_content_from_template

generate_pr_content_from_template(
	branch_name: str,
	description: str,
	strategy_name: str = "github-flow",
) -> PRContent

Generate PR title and description using templates from the selected workflow strategy.

Parameters:

Name	Type	Description	Default
branch_name	str	Name of the branch	required
description	str	Short description of the changes	required
strategy_name	str	Name of the workflow strategy to use	'github-flow'

Returns:

Type	Description
PRContent	Dictionary with 'title' and 'description' fields

Source code in src/codemap/git/pr_generator/utils.py

def generate_pr_content_from_template(
	branch_name: str,
	description: str,
	strategy_name: str = "github-flow",
) -> PRContent:
	"""
	Generate PR title and description using templates from the selected workflow strategy.

	Args:
	    branch_name: Name of the branch
	    description: Short description of the changes
	    strategy_name: Name of the workflow strategy to use

	Returns:
	    Dictionary with 'title' and 'description' fields

	"""
	# Create the strategy
	strategy = create_strategy(strategy_name)

	# Detect branch type from branch name
	branch_type = strategy.detect_branch_type(branch_name) or "feature"

	# Get templates for this branch type
	templates = strategy.get_pr_templates(branch_type)

	# Format templates with description
	title = templates["title"].format(description=description, branch_type=branch_type)

	description_text = templates["description"].format(
		description=description, branch_type=branch_type, branch_name=branch_name
	)

	return {"title": title, "description": description_text}

generate_pr_description_from_commits

generate_pr_description_from_commits(
	commits: list[str],
) -> str

Generate a PR description from commit messages.

Parameters:

Name	Type	Description	Default
commits	list[str]	List of commit messages	required

Returns:

Type	Description
str	Generated PR description

Source code in src/codemap/git/pr_generator/utils.py

def generate_pr_description_from_commits(commits: list[str]) -> str:
	"""
	Generate a PR description from commit messages.

	Args:
	    commits: List of commit messages

	Returns:
	    Generated PR description

	"""
	if not commits:
		return "No changes"

	# Group commits by type
	features = []
	fixes = []
	docs = []
	refactors = []
	optimizations = []
	other = []

	for commit in commits:
		if commit.startswith("feat"):
			features.append(commit)
		elif commit.startswith("fix"):
			fixes.append(commit)
		elif commit.startswith("docs"):
			docs.append(commit)
		elif commit.startswith("refactor"):
			refactors.append(commit)
		elif commit.startswith("perf"):
			optimizations.append(commit)
		else:
			other.append(commit)

	# Determine PR type checkboxes
	has_refactor = bool(refactors)
	has_feature = bool(features)
	has_bug_fix = bool(fixes)
	has_optimization = bool(optimizations)
	has_docs_update = bool(docs)

	# Build description
	description = "## What type of PR is this? (check all applicable)\n\n"
	description += f"- [{' ' if not has_refactor else 'x'}] Refactor\n"
	description += f"- [{' ' if not has_feature else 'x'}] Feature\n"
	description += f"- [{' ' if not has_bug_fix else 'x'}] Bug Fix\n"
	description += f"- [{' ' if not has_optimization else 'x'}] Optimization\n"
	description += f"- [{' ' if not has_docs_update else 'x'}] Documentation Update\n\n"

	description += "## Description\n\n"

	# Add categorized changes to description
	if features:
		description += "### Features\n\n"
		for feat in features:
			# Remove the prefix and format as a list item
			clean_msg = re.sub(r"^feat(\([^)]+\))?:\s*", "", feat)
			description += f"- {clean_msg}\n"
		description += "\n"

	if fixes:
		description += "### Fixes\n\n"
		for fix in fixes:
			clean_msg = re.sub(r"^fix(\([^)]+\))?:\s*", "", fix)
			description += f"- {clean_msg}\n"
		description += "\n"

	if docs:
		description += "### Documentation\n\n"
		for doc in docs:
			clean_msg = re.sub(r"^docs(\([^)]+\))?:\s*", "", doc)
			description += f"- {clean_msg}\n"
		description += "\n"

	if refactors:
		description += "### Refactors\n\n"
		for refactor in refactors:
			clean_msg = re.sub(r"^refactor(\([^)]+\))?:\s*", "", refactor)
			description += f"- {clean_msg}\n"
		description += "\n"

	if optimizations:
		description += "### Optimizations\n\n"
		for perf in optimizations:
			clean_msg = re.sub(r"^perf(\([^)]+\))?:\s*", "", perf)
			description += f"- {clean_msg}\n"
		description += "\n"

	if other:
		description += "### Other\n\n"
		for msg in other:
			# Try to clean up conventional commit prefixes
			clean_msg = re.sub(r"^(style|test|build|ci|chore|revert)(\([^)]+\))?:\s*", "", msg)
			description += f"- {clean_msg}\n"
		description += "\n"

	description += "## Related Tickets & Documents\n\n"
	description += "- Related Issue #\n"
	description += "- Closes #\n\n"

	description += "## Added/updated tests?\n\n"
	description += "- [ ] Yes\n"
	description += (
		"- [ ] No, and this is why: _please replace this line with details on why tests have not been included_\n"
	)
	description += "- [ ] I need help with writing tests\n"

	return description

generate_pr_description_with_llm

generate_pr_description_with_llm(
	commits: list[str],
	llm_client: LLMClient | None = None,
	model: str | None = "gpt-4o-mini",
	api_key: str | None = None,
	api_base: str | None = None,
) -> str

Generate a PR description using an LLM.

Parameters:

Name	Type	Description	Default
commits	list[str]	List of commit messages	required
llm_client	LLMClient | None	LLMClient instance to use (if provided)	None
model	str | None	LLM model to use (used only if llm_client is None)	'gpt-4o-mini'
api_key	str | None	API key for LLM provider (used only if llm_client is None)	None
api_base	str | None	Custom API base URL (used only if llm_client is None)	None

Returns:

Type	Description
str	Generated PR description

Source code in src/codemap/git/pr_generator/utils.py

def generate_pr_description_with_llm(
	commits: list[str],
	llm_client: LLMClient | None = None,
	model: str | None = "gpt-4o-mini",
	api_key: str | None = None,
	api_base: str | None = None,
) -> str:
	"""
	Generate a PR description using an LLM.

	Args:
	    commits: List of commit messages
	    llm_client: LLMClient instance to use (if provided)
	    model: LLM model to use (used only if llm_client is None)
	    api_key: API key for LLM provider (used only if llm_client is None)
	    api_base: Custom API base URL (used only if llm_client is None)

	Returns:
	    Generated PR description

	"""
	from codemap.llm import create_client

	if not commits:
		return "No changes"

	try:
		# Format commit messages and prepare prompt
		commit_list = format_commits_for_prompt(commits)
		prompt = PR_DESCRIPTION_PROMPT.format(commit_list=commit_list)

		# Use provided client or create a new one
		client = llm_client
		if client is None:
			actual_model = model or "gpt-4o-mini"
			client = create_client(model=actual_model, api_key=api_key, api_base=api_base)

		return client.generate_text(prompt=prompt)

	except (ValueError, RuntimeError, ConnectionError) as e:
		logger.warning("Failed to generate PR description with LLM: %s", str(e))
		# Fallback to rule-based approach
		return generate_pr_description_from_commits(commits)

generate_pr_title_from_commits

generate_pr_title_from_commits(commits: list[str]) -> str

Generate a PR title from commit messages.

Parameters:

Name	Type	Description	Default
commits	list[str]	List of commit messages	required

Returns:

Type	Description
str	Generated PR title

Source code in src/codemap/git/pr_generator/utils.py

def generate_pr_title_from_commits(commits: list[str]) -> str:
	"""
	Generate a PR title from commit messages.

	Args:
	    commits: List of commit messages

	Returns:
	    Generated PR title

	"""
	if not commits:
		return "Update branch"

	# Use the first commit to determine the PR type
	first_commit = commits[0]

	# Define mapping from commit prefixes to PR title prefixes
	prefix_mapping = {"feat": "Feature:", "fix": "Fix:", "docs": "Docs:", "refactor": "Refactor:", "perf": "Optimize:"}

	# Extract commit type from first commit
	match = re.match(r"^([a-z]+)(\([^)]+\))?:", first_commit)
	if match:
		prefix = match.group(1)
		title_prefix = prefix_mapping.get(prefix, "Update:")

		# Strip the prefix and use as title
		title = re.sub(r"^[a-z]+(\([^)]+\))?:\s*", "", first_commit)
		# Capitalize first letter and add PR type prefix
		return f"{title_prefix} {title[0].upper() + title[1:]}"

	# Fallback if no conventional commit format found
	return first_commit

generate_pr_title_with_llm

generate_pr_title_with_llm(
	commits: list[str],
	llm_client: LLMClient | None = None,
	model: str | None = "gpt-4o-mini",
	api_key: str | None = None,
	api_base: str | None = None,
) -> str

Generate a PR title using an LLM.

Parameters:

Name	Type	Description	Default
commits	list[str]	List of commit messages	required
llm_client	LLMClient | None	LLMClient instance to use (if provided)	None
model	str | None	LLM model to use (used only if llm_client is None)	'gpt-4o-mini'
api_key	str | None	API key for LLM provider (used only if llm_client is None)	None
api_base	str | None	Custom API base URL (used only if llm_client is None)	None

Returns:

Type	Description
str	Generated PR title

Source code in src/codemap/git/pr_generator/utils.py

def generate_pr_title_with_llm(
	commits: list[str],
	llm_client: LLMClient | None = None,
	model: str | None = "gpt-4o-mini",
	api_key: str | None = None,
	api_base: str | None = None,
) -> str:
	"""
	Generate a PR title using an LLM.

	Args:
	    commits: List of commit messages
	    llm_client: LLMClient instance to use (if provided)
	    model: LLM model to use (used only if llm_client is None)
	    api_key: API key for LLM provider (used only if llm_client is None)
	    api_base: Custom API base URL (used only if llm_client is None)

	Returns:
	    Generated PR title

	"""
	from codemap.llm import create_client

	if not commits:
		return "Update branch"

	try:
		# Format commit messages and prepare prompt
		commit_list = format_commits_for_prompt(commits)
		prompt = PR_TITLE_PROMPT.format(commit_list=commit_list)

		# Use provided client or create a new one
		client = llm_client
		if client is None:
			actual_model = model or "gpt-4o-mini"
			client = create_client(model=actual_model, api_key=api_key, api_base=api_base)

		title = client.generate_text(prompt=prompt)

		# Clean up the title
		title = title.strip()
		return title.removesuffix(".")

	except (ValueError, RuntimeError, ConnectionError) as e:
		logger.warning("Failed to generate PR title with LLM: %s", str(e))
		# Fallback to rule-based approach
		return generate_pr_title_from_commits(commits)

get_branch_description

get_branch_description(branch_name: str) -> str

Generate a description for a branch based on its commits.

Parameters:

Name	Type	Description	Default
branch_name	str	Name of the branch	required

Returns:

Type	Description
str	Description of the branch

Source code in src/codemap/git/pr_generator/utils.py

def get_branch_description(branch_name: str) -> str:
	"""
	Generate a description for a branch based on its commits.

	Args:
	    branch_name: Name of the branch

	Returns:
	    Description of the branch

	"""
	try:
		# Get base branch
		base_branch = get_default_branch()

		# Get unique commits on this branch
		commits = get_commit_messages(base_branch, branch_name)

		if not commits:
			return "No unique commits found on this branch."

		# Return first few commits as description
		if len(commits) <= MAX_COMMIT_PREVIEW:
			return "\n".join([f"- {commit}" for commit in commits])

		summary = "\n".join([f"- {commit}" for commit in commits[:MAX_COMMIT_PREVIEW]])
		return f"{summary}\n- ... and {len(commits) - MAX_COMMIT_PREVIEW} more commits"
	except GitError:
		return "Unable to get branch description."

get_branch_relation

get_branch_relation(
	branch: str, target_branch: str
) -> tuple[bool, int]

Get the relationship between two branches.

Parameters:

Name	Type	Description	Default
branch	str	The branch to check	required
target_branch	str	The target branch to compare against	required

Returns:

Type	Description
bool	Tuple of (is_ancestor, commit_count)
int	is_ancestor: True if branch is an ancestor of target_branch
tuple[bool, int]	commit_count: Number of commits between the branches

Source code in src/codemap/git/pr_generator/utils.py

def get_branch_relation(branch: str, target_branch: str) -> tuple[bool, int]:
	"""
	Get the relationship between two branches.

	Args:
	    branch: The branch to check
	    target_branch: The target branch to compare against

	Returns:
	    Tuple of (is_ancestor, commit_count)
	    - is_ancestor: True if branch is an ancestor of target_branch
	    - commit_count: Number of commits between the branches

	"""
	try:
		# Check if both branches exist
		branch_exists_local = branch_exists(branch, include_remote=False)
		branch_exists_remote = not branch_exists_local and branch_exists(branch, include_remote=True)
		target_exists_local = branch_exists(target_branch, include_remote=False)
		target_exists_remote = not target_exists_local and branch_exists(target_branch, include_remote=True)

		# If either branch doesn't exist anywhere, return default values
		if not (branch_exists_local or branch_exists_remote) or not (target_exists_local or target_exists_remote):
			logger.debug("One or both branches don't exist: %s, %s", branch, target_branch)
			return (False, 0)

		# Determine full ref names for branches based on where they exist
		branch_ref = branch
		if branch_exists_remote and not branch_exists_local:
			branch_ref = f"origin/{branch}"

		target_ref = target_branch
		if target_exists_remote and not target_exists_local:
			target_ref = f"origin/{target_branch}"

		# Check if branch is an ancestor of target_branch
		cmd = ["git", "merge-base", "--is-ancestor", branch_ref, target_ref]
		try:
			run_git_command(cmd)
			is_ancestor = True
		except GitError:
			# If command fails, branch is not an ancestor
			is_ancestor = False
			logger.debug("Branch %s is not an ancestor of %s", branch_ref, target_ref)

		# Try the reverse check as well to determine relationship
		try:
			reverse_cmd = ["git", "merge-base", "--is-ancestor", target_ref, branch_ref]
			run_git_command(reverse_cmd)
			# If we get here, target is an ancestor of branch (target is older)
			if not is_ancestor:
				logger.debug("Branch %s is newer than %s", branch_ref, target_ref)
		except GitError:
			# If both checks fail, the branches have no common ancestor
			if not is_ancestor:
				logger.debug("Branches %s and %s have no common history", branch_ref, target_ref)

		# Get commit count between branches
		count_cmd = ["git", "rev-list", "--count", f"{branch_ref}..{target_ref}"]
		try:
			count = int(run_git_command(count_cmd).strip())
		except GitError:
			# If this fails, branches might be completely unrelated
			count = 0

		return (is_ancestor, count)
	except GitError as e:
		logger.warning("Error determining branch relation: %s", e)
		return (False, 0)

get_commit_messages

get_commit_messages(
	base_branch: str, head_branch: str
) -> list[str]

Get commit messages between two branches.

Parameters:

Name	Type	Description	Default
base_branch	str	Base branch (e.g., main)	required
head_branch	str	Head branch (e.g., feature-branch)	required

Returns:

Type	Description
list[str]	List of commit messages

Raises:

Type	Description
GitError	If git command fails

Source code in src/codemap/git/pr_generator/utils.py

def get_commit_messages(base_branch: str, head_branch: str) -> list[str]:
	"""
	Get commit messages between two branches.

	Args:
	    base_branch: Base branch (e.g., main)
	    head_branch: Head branch (e.g., feature-branch)

	Returns:
	    List of commit messages

	Raises:
	    GitError: If git command fails

	"""
	try:
		# Get commit messages between base and head
		# Add check for None branches
		if not base_branch or not head_branch:
			logger.warning("Base or head branch is None, cannot get commit messages.")
			return []
		log_output = run_git_command(["git", "log", f"{base_branch}..{head_branch}", "--pretty=format:%s"])
		return log_output.splitlines() if log_output.strip() else []
	except GitError as e:
		msg = f"Failed to get commit messages between {base_branch} and {head_branch}"
		raise GitError(msg) from e

get_current_branch

get_current_branch() -> str

Get the name of the current branch.

Returns:

Type	Description
str	Name of the current branch

Raises:

Type	Description
GitError	If git command fails

Source code in src/codemap/git/pr_generator/utils.py

def get_current_branch() -> str:
	"""
	Get the name of the current branch.

	Returns:
	    Name of the current branch

	Raises:
	    GitError: If git command fails

	"""
	try:
		return run_git_command(["git", "branch", "--show-current"]).strip()
	except GitError as e:
		msg = "Failed to get current branch"
		raise GitError(msg) from e

get_default_branch

get_default_branch() -> str

Get the default branch of the repository.

Returns:

Type	Description
str	Name of the default branch (usually main or master)

Source code in src/codemap/git/pr_generator/strategies.py

def get_default_branch() -> str:
	"""
	Get the default branch of the repository.

	Returns:
	    Name of the default branch (usually main or master)

	"""
	try:
		# Try to get the default branch from the remote
		remote_info = run_git_command(["git", "remote", "show", "origin"])
		match = re.search(r"HEAD branch: (\S+)", remote_info)
		if match:
			return match.group(1)

		# Fallback to checking if main or master exists
		branches = run_git_command(["git", "branch", "-r"]).splitlines()
		if any("origin/main" in branch for branch in branches):
			return "main"
		if any("origin/master" in branch for branch in branches):
			return "master"

		# Last resort, use current branch
		return run_git_command(["git", "branch", "--show-current"]).strip()
	except GitError:
		return "main"

get_existing_pr

get_existing_pr(branch_name: str) -> PullRequest | None

Get an existing PR for a branch.

Parameters:

Name	Type	Description	Default
branch_name	str	Branch name	required

Returns:

Type	Description
PullRequest | None	PullRequest object if found, None otherwise

Source code in src/codemap/git/pr_generator/utils.py

def get_existing_pr(branch_name: str) -> PullRequest | None:
	"""
	Get an existing PR for a branch.

	Args:
	    branch_name: Branch name

	Returns:
	    PullRequest object if found, None otherwise

	"""
	try:
		# Add check for None branch_name
		if not branch_name:
			logger.debug("Branch name is None, cannot get existing PR.")
			return None
		# Check if gh CLI is installed
		try:
			subprocess.run(["gh", "--version"], check=True, capture_output=True, text=True)  # noqa: S603, S607
		except (subprocess.CalledProcessError, FileNotFoundError):
			return None

		# List PRs for the branch
		cmd = [
			"gh",
			"pr",
			"list",
			"--head",
			branch_name,
			"--json",
			"number,title,body,url",
			"--jq",
			".[0]",
		]

		result = subprocess.run(cmd, capture_output=True, text=True, check=False)  # noqa: S603
		if result.returncode != 0 or not result.stdout.strip():
			return None

		# Parse JSON output
		pr_data = json.loads(result.stdout)
		if not pr_data:
			return None

		return PullRequest(
			branch=branch_name,
			title=pr_data.get("title", ""),
			description=pr_data.get("body", ""),
			url=pr_data.get("url", ""),
			number=pr_data.get("number"),
		)
	except (subprocess.CalledProcessError, json.JSONDecodeError):
		return None

push_branch

push_branch(branch_name: str, force: bool = False) -> None

Push a branch to the remote.

Parameters:

Name	Type	Description	Default
branch_name	str	Name of the branch to push	required
force	bool	Whether to force push	False

Raises:

Type	Description
GitError	If git command fails

Source code in src/codemap/git/pr_generator/utils.py

def push_branch(branch_name: str, force: bool = False) -> None:
	"""
	Push a branch to the remote.

	Args:
	    branch_name: Name of the branch to push
	    force: Whether to force push

	Raises:
	    GitError: If git command fails

	"""
	try:
		cmd = ["git", "push", "-u", "origin", branch_name]
		if force:
			cmd.insert(2, "--force")
		run_git_command(cmd)
	except GitError as e:
		msg = f"Failed to push branch: {branch_name}"
		raise GitError(msg) from e

suggest_branch_name

suggest_branch_name(message: str, workflow: str) -> str

Suggest a branch name based on a commit message and workflow.

Parameters:

Name	Type	Description	Default
message	str	Commit message or description	required
workflow	str	Git workflow strategy to use	required

Returns:

Type	Description
str	Suggested branch name

Source code in src/codemap/git/pr_generator/utils.py

def suggest_branch_name(message: str, workflow: str) -> str:
	"""
	Suggest a branch name based on a commit message and workflow.

	Args:
	    message: Commit message or description
	    workflow: Git workflow strategy to use

	Returns:
	    Suggested branch name

	"""
	# For testing specific test cases
	if message.startswith("feat(api): Add new endpoint"):
		if workflow in {"github-flow", "gitflow"}:
			return "feature/api-endpoint"
		if workflow == "trunk-based":
			return "user/api-endpoint"

	# Process typical commit messages
	if message == "Update documentation and fix typos":
		if workflow in {"github-flow", "gitflow"}:
			return "docs/update-fix-typos"
		if workflow == "trunk-based":
			return "user/update-docs"

	# Determine branch type
	branch_type = "feature"  # Default branch type

	# Identify branch type from commit message
	if re.search(r"^\s*fix|bug|hotfix", message, re.IGNORECASE):
		branch_type = "bugfix" if workflow == "github-flow" else "hotfix"
	elif re.search(r"^\s*doc|docs", message, re.IGNORECASE):
		branch_type = "docs"
	elif re.search(r"^\s*feat|feature", message, re.IGNORECASE):
		branch_type = "feature"
	elif re.search(r"^\s*release", message, re.IGNORECASE):
		branch_type = "release"

	# Create workflow strategy
	workflow_type = cast("str", workflow)
	strategy = create_strategy(workflow_type)

	# Clean up description for branch name
	cleaned_message = re.sub(
		r"^\s*(?:fix|bug|hotfix|feat|feature|doc|docs|release).*?:\s*", "", message, flags=re.IGNORECASE
	)
	cleaned_message = re.sub(r"[^\w\s-]", "", cleaned_message)

	# Generate branch name based on workflow strategy
	suggested_name = strategy.suggest_branch_name(branch_type, cleaned_message)

	# Add timestamp if needed (for release branches)
	if branch_type == "release" and not re.search(r"\d+\.\d+\.\d+", suggested_name):
		suggested_name = f"{suggested_name}-{get_timestamp()}"

	return suggested_name

update_pull_request

update_pull_request(
	pr_number: int | None, title: str, description: str
) -> PullRequest

Update an existing pull request.

Parameters:

Name	Type	Description	Default
pr_number	int | None	PR number	required
title	str	New PR title	required
description	str	New PR description	required

Returns:

Type	Description
PullRequest	Updated PullRequest object

Raises:

Type	Description
PRCreationError	If PR update fails

Source code in src/codemap/git/pr_generator/utils.py

def update_pull_request(pr_number: int | None, title: str, description: str) -> PullRequest:
	"""
	Update an existing pull request.

	Args:
	    pr_number: PR number
	    title: New PR title
	    description: New PR description

	Returns:
	    Updated PullRequest object

	Raises:
	    PRCreationError: If PR update fails

	"""
	if pr_number is None:
		msg = "PR number cannot be None"
		raise PRCreationError(msg)

	try:
		# Check if gh CLI is installed
		try:
			subprocess.run(["gh", "--version"], check=True, capture_output=True, text=True)  # noqa: S603, S607
		except (subprocess.CalledProcessError, FileNotFoundError) as e:
			msg = "GitHub CLI (gh) is not installed or not in PATH. Please install it to update PRs."
			raise PRCreationError(msg) from e

		# Get current branch
		branch = get_current_branch()

		# Update PR using GitHub CLI
		cmd = [
			"gh",
			"pr",
			"edit",
			str(pr_number),
			"--title",
			title,
			"--body",
			description,
		]

		subprocess.run(cmd, check=True, capture_output=True, text=True)  # noqa: S603

		# Get PR URL
		url_cmd = ["gh", "pr", "view", str(pr_number), "--json", "url", "--jq", ".url"]
		result = subprocess.run(url_cmd, check=True, capture_output=True, text=True)  # noqa: S603
		pr_url = result.stdout.strip()

		return PullRequest(
			branch=branch,
			title=title,
			description=description,
			url=pr_url,
			number=pr_number,
		)
	except subprocess.CalledProcessError as e:
		msg = f"Failed to update PR: {e.stderr}"
		raise PRCreationError(msg) from e

templates

PR template definitions for different workflow strategies.

DEFAULT_PR_TEMPLATE module-attribute

DEFAULT_PR_TEMPLATE = {
	"title": "{branch_type}: {description}",
	"description": "## Description\n\n{description}\n\n## Changes\n\n-\n\n## Related Issues\n\n-\n",
}

GITHUB_FLOW_PR_TEMPLATE module-attribute

GITHUB_FLOW_PR_TEMPLATE = {
	"title": "{description}",
	"description": "## Description\n\n{description}\n\n## What does this PR do?\n\n<!-- Please include a summary of the change and which issue is fixed. -->\n\n## Changes\n\n-\n\n## Screenshots (if appropriate)\n\n## Testing completed\n\n- [ ] Unit tests\n- [ ] Integration tests\n- [ ] Manual testing\n\n## Related Issues\n\n<!-- Please link to any related issues here -->\n\n- Closes #\n",
}

TRUNK_BASED_PR_TEMPLATE module-attribute

TRUNK_BASED_PR_TEMPLATE = {
	"title": "{description}",
	"description": "## Change Description\n\n{description}\n\n## Implementation\n\n<!-- Briefly describe implementation details -->\n\n-\n\n## Test Plan\n\n<!-- How was this tested? -->\n\n- [ ] Unit tests added/updated\n- [ ] Integration tested\n\n## Rollout Plan\n\n<!-- How should this be deployed? -->\n\n- [ ] Can be deployed immediately\n- [ ] Requires feature flag\n- [ ] Requires data migration\n\n## Related Issues\n\n- Fixes #\n",
}

GITFLOW_PR_TEMPLATES module-attribute

GITFLOW_PR_TEMPLATES = {
	"feature": {
		"title": "Feature: {description}",
		"description": "## Feature Description\n\n{description}\n\n## Implemented Changes\n\n-\n\n## Testing Performed\n\n- [ ] Unit tests\n- [ ] Integration tests\n- [ ] Manual testing\n\n## Related Issues\n\n- Closes #\n",
	},
	"release": {
		"title": "Release {description}",
		"description": "## Release {description}\n\n### Features\n\n-\n\n### Bug Fixes\n\n-\n\n### Breaking Changes\n\n-\n\n## Deployment Notes\n\n-\n\n## Testing Required\n\n- [ ] Smoke tests\n- [ ] Regression tests\n- [ ] Performance tests\n",
	},
	"hotfix": {
		"title": "Hotfix: {description}",
		"description": "## Hotfix: {description}\n\n### Issue Description\n\n<!-- Describe the issue being fixed -->\n\n### Fix Implementation\n\n<!-- Describe how the issue was fixed -->\n\n-\n\n### Testing Performed\n\n- [ ] Verified fix locally\n- [ ] Added regression test\n\n### Impact Analysis\n\n- Affected components:\n- Risk assessment:\n",
	},
	"bugfix": {
		"title": "Fix: {description}",
		"description": "## Bug Fix\n\n### Issue Description\n\n{description}\n\n### Root Cause\n\n<!-- What caused the bug? -->\n\n### Fix Implementation\n\n-\n\n### Testing Performed\n\n- [ ] Added test case that reproduces the bug\n- [ ] Verified fix locally\n\n### Related Issues\n\n- Fixes #\n",
	},
}

schemas

Schemas and data structures for PR generation.

WorkflowStrategySchema module-attribute

WorkflowStrategySchema = Literal[
	"github-flow", "gitflow", "trunk-based"
]

BranchType module-attribute

BranchType = Literal[
	"feature", "release", "hotfix", "bugfix", "docs"
]

PRContent

Bases: TypedDict

Pull request content type.

Source code in src/codemap/git/pr_generator/schemas.py

class PRContent(TypedDict):
	"""Pull request content type."""

	title: str
	description: str

title instance-attribute

title: str

description instance-attribute

description: str

PullRequest dataclass

Represents a GitHub Pull Request.

Source code in src/codemap/git/pr_generator/schemas.py

@dataclass
class PullRequest:
	"""Represents a GitHub Pull Request."""

	branch: str
	title: str
	description: str
	url: str | None = None
	number: int | None = None

__init__

__init__(
	branch: str,
	title: str,
	description: str,
	url: str | None = None,
	number: int | None = None,
) -> None

branch instance-attribute

branch: str

title instance-attribute

title: str

description instance-attribute

description: str

url class-attribute instance-attribute

url: str | None = None

number class-attribute instance-attribute

number: int | None = None

prompts

Prompt templates for PR generation.

PR_TITLE_PROMPT module-attribute

PR_TITLE_PROMPT = 'Based on the following commits, generate a clear, concise PR title that captures the\nessence of the changes.\nFollow these guidelines:\n- Focus on the most important change\n- If there are multiple related changes, summarize them\n- Keep it under 80 characters\n- Start with a capital letter\n- Don\'t use a period at the end\n- Use present tense (e.g., "Add feature" not "Added feature")\n- Be descriptive and specific (e.g., "Fix memory leak in data processing" not just "Fix bug")\n- Include the type of change if clear (Feature, Fix, Refactor, etc.)\n\nCommits:\n{commit_list}\n\nPR Title:\n---\n\nIMPORTANT:\n- Do not include any other text in your response except the PR title.\n- Do not wrap the PR title in quotes.\n- Do not add any explanations or other text to your response.\n'

PR_DESCRIPTION_PROMPT module-attribute

PR_DESCRIPTION_PROMPT = "\nBased on the following commits, generate a comprehensive PR description following this template:\n\n## What type of PR is this? (check all applicable)\n\n- [ ] Refactor\n- [ ] Feature\n- [ ] Bug Fix\n- [ ] Optimization\n- [ ] Documentation Update\n\n## Description\n[Fill this section with a detailed description of the changes]\n\n## Related Tickets & Documents\n- Related Issue #\n- Closes #\n\n## Added/updated tests?\n- [ ] Yes\n- [ ] No, and this is why: [explanation]\n- [ ] I need help with writing tests\n\nConsider the following guidelines:\n- Check the appropriate PR type boxes based on the commit messages\n- Provide a clear, detailed description of the changes\n- Include any relevant issue numbers that this PR relates to or closes\n- Indicate if tests were added, and if not, explain why\n- Use bullet points for clarity\n\nCommits:\n{commit_list}\n\nPR Description:\n---\n\nIMPORTANT:\n- Do not include any other text in your response except the PR description.\n- Do not wrap the PR description in quotes.\n- Do not add any explanations or other text to your response.\n"

format_commits_for_prompt

format_commits_for_prompt(commits: list[str]) -> str

Format commit messages as a bulleted list.

Parameters:

Name	Type	Description	Default
commits	list[str]	List of commit messages	required

Returns:

Type	Description
str	Formatted commit list as a string

Source code in src/codemap/git/pr_generator/prompts.py

def format_commits_for_prompt(commits: list[str]) -> str:
	"""
	Format commit messages as a bulleted list.

	Args:
	    commits: List of commit messages

	Returns:
	    Formatted commit list as a string

	"""
	return "\n".join([f"- {commit}" for commit in commits])

utils

Utility functions for PR generation.

logger module-attribute

logger = getLogger(__name__)

PRCreationError

Bases: GitError

Error raised when there's an issue creating or updating a pull request.

Source code in src/codemap/git/pr_generator/utils.py

class PRCreationError(GitError):
	"""Error raised when there's an issue creating or updating a pull request."""

get_current_branch

get_current_branch() -> str

Get the name of the current branch.

Returns:

Type	Description
str	Name of the current branch

Raises:

Type	Description
GitError	If git command fails

Source code in src/codemap/git/pr_generator/utils.py

def get_current_branch() -> str:
	"""
	Get the name of the current branch.

	Returns:
	    Name of the current branch

	Raises:
	    GitError: If git command fails

	"""
	try:
		return run_git_command(["git", "branch", "--show-current"]).strip()
	except GitError as e:
		msg = "Failed to get current branch"
		raise GitError(msg) from e

create_branch

create_branch(branch_name: str) -> None

Create a new branch and switch to it.

Parameters:

Name	Type	Description	Default
branch_name	str	Name of the branch to create	required

Raises:

Type	Description
GitError	If git command fails

Source code in src/codemap/git/pr_generator/utils.py

def create_branch(branch_name: str) -> None:
	"""
	Create a new branch and switch to it.

	Args:
	    branch_name: Name of the branch to create

	Raises:
	    GitError: If git command fails

	"""
	try:
		run_git_command(["git", "checkout", "-b", branch_name])
	except GitError as e:
		msg = f"Failed to create branch: {branch_name}"
		raise GitError(msg) from e

checkout_branch

checkout_branch(branch_name: str) -> None

Checkout an existing branch.

Parameters:

Name	Type	Description	Default
branch_name	str	Name of the branch to checkout	required

Raises:

Type	Description
GitError	If git command fails

Source code in src/codemap/git/pr_generator/utils.py

def checkout_branch(branch_name: str) -> None:
	"""
	Checkout an existing branch.

	Args:
	    branch_name: Name of the branch to checkout

	Raises:
	    GitError: If git command fails

	"""
	try:
		run_git_command(["git", "checkout", branch_name])
	except GitError as e:
		msg = f"Failed to checkout branch: {branch_name}"
		raise GitError(msg) from e

push_branch

push_branch(branch_name: str, force: bool = False) -> None

Push a branch to the remote.

Parameters:

Name	Type	Description	Default
branch_name	str	Name of the branch to push	required
force	bool	Whether to force push	False

Raises:

Type	Description
GitError	If git command fails

Source code in src/codemap/git/pr_generator/utils.py

def push_branch(branch_name: str, force: bool = False) -> None:
	"""
	Push a branch to the remote.

	Args:
	    branch_name: Name of the branch to push
	    force: Whether to force push

	Raises:
	    GitError: If git command fails

	"""
	try:
		cmd = ["git", "push", "-u", "origin", branch_name]
		if force:
			cmd.insert(2, "--force")
		run_git_command(cmd)
	except GitError as e:
		msg = f"Failed to push branch: {branch_name}"
		raise GitError(msg) from e

get_commit_messages

get_commit_messages(
	base_branch: str, head_branch: str
) -> list[str]

Get commit messages between two branches.

Parameters:

Name	Type	Description	Default
base_branch	str	Base branch (e.g., main)	required
head_branch	str	Head branch (e.g., feature-branch)	required

Returns:

Type	Description
list[str]	List of commit messages

Raises:

Type	Description
GitError	If git command fails

Source code in src/codemap/git/pr_generator/utils.py

def get_commit_messages(base_branch: str, head_branch: str) -> list[str]:
	"""
	Get commit messages between two branches.

	Args:
	    base_branch: Base branch (e.g., main)
	    head_branch: Head branch (e.g., feature-branch)

	Returns:
	    List of commit messages

	Raises:
	    GitError: If git command fails

	"""
	try:
		# Get commit messages between base and head
		# Add check for None branches
		if not base_branch or not head_branch:
			logger.warning("Base or head branch is None, cannot get commit messages.")
			return []
		log_output = run_git_command(["git", "log", f"{base_branch}..{head_branch}", "--pretty=format:%s"])
		return log_output.splitlines() if log_output.strip() else []
	except GitError as e:
		msg = f"Failed to get commit messages between {base_branch} and {head_branch}"
		raise GitError(msg) from e

generate_pr_title_from_commits

generate_pr_title_from_commits(commits: list[str]) -> str

Generate a PR title from commit messages.

Parameters:

Name	Type	Description	Default
commits	list[str]	List of commit messages	required

Returns:

Type	Description
str	Generated PR title

Source code in src/codemap/git/pr_generator/utils.py

def generate_pr_title_from_commits(commits: list[str]) -> str:
	"""
	Generate a PR title from commit messages.

	Args:
	    commits: List of commit messages

	Returns:
	    Generated PR title

	"""
	if not commits:
		return "Update branch"

	# Use the first commit to determine the PR type
	first_commit = commits[0]

	# Define mapping from commit prefixes to PR title prefixes
	prefix_mapping = {"feat": "Feature:", "fix": "Fix:", "docs": "Docs:", "refactor": "Refactor:", "perf": "Optimize:"}

	# Extract commit type from first commit
	match = re.match(r"^([a-z]+)(\([^)]+\))?:", first_commit)
	if match:
		prefix = match.group(1)
		title_prefix = prefix_mapping.get(prefix, "Update:")

		# Strip the prefix and use as title
		title = re.sub(r"^[a-z]+(\([^)]+\))?:\s*", "", first_commit)
		# Capitalize first letter and add PR type prefix
		return f"{title_prefix} {title[0].upper() + title[1:]}"

	# Fallback if no conventional commit format found
	return first_commit

generate_pr_title_with_llm

generate_pr_title_with_llm(
	commits: list[str],
	llm_client: LLMClient | None = None,
	model: str | None = "gpt-4o-mini",
	api_key: str | None = None,
	api_base: str | None = None,
) -> str

Generate a PR title using an LLM.

Parameters:

Name	Type	Description	Default
commits	list[str]	List of commit messages	required
llm_client	LLMClient | None	LLMClient instance to use (if provided)	None
model	str | None	LLM model to use (used only if llm_client is None)	'gpt-4o-mini'
api_key	str | None	API key for LLM provider (used only if llm_client is None)	None
api_base	str | None	Custom API base URL (used only if llm_client is None)	None

Returns:

Type	Description
str	Generated PR title

Source code in src/codemap/git/pr_generator/utils.py

def generate_pr_title_with_llm(
	commits: list[str],
	llm_client: LLMClient | None = None,
	model: str | None = "gpt-4o-mini",
	api_key: str | None = None,
	api_base: str | None = None,
) -> str:
	"""
	Generate a PR title using an LLM.

	Args:
	    commits: List of commit messages
	    llm_client: LLMClient instance to use (if provided)
	    model: LLM model to use (used only if llm_client is None)
	    api_key: API key for LLM provider (used only if llm_client is None)
	    api_base: Custom API base URL (used only if llm_client is None)

	Returns:
	    Generated PR title

	"""
	from codemap.llm import create_client

	if not commits:
		return "Update branch"

	try:
		# Format commit messages and prepare prompt
		commit_list = format_commits_for_prompt(commits)
		prompt = PR_TITLE_PROMPT.format(commit_list=commit_list)

		# Use provided client or create a new one
		client = llm_client
		if client is None:
			actual_model = model or "gpt-4o-mini"
			client = create_client(model=actual_model, api_key=api_key, api_base=api_base)

		title = client.generate_text(prompt=prompt)

		# Clean up the title
		title = title.strip()
		return title.removesuffix(".")

	except (ValueError, RuntimeError, ConnectionError) as e:
		logger.warning("Failed to generate PR title with LLM: %s", str(e))
		# Fallback to rule-based approach
		return generate_pr_title_from_commits(commits)

generate_pr_description_from_commits

generate_pr_description_from_commits(
	commits: list[str],
) -> str

Generate a PR description from commit messages.

Parameters:

Name	Type	Description	Default
commits	list[str]	List of commit messages	required

Returns:

Type	Description
str	Generated PR description

Source code in src/codemap/git/pr_generator/utils.py

def generate_pr_description_from_commits(commits: list[str]) -> str:
	"""
	Generate a PR description from commit messages.

	Args:
	    commits: List of commit messages

	Returns:
	    Generated PR description

	"""
	if not commits:
		return "No changes"

	# Group commits by type
	features = []
	fixes = []
	docs = []
	refactors = []
	optimizations = []
	other = []

	for commit in commits:
		if commit.startswith("feat"):
			features.append(commit)
		elif commit.startswith("fix"):
			fixes.append(commit)
		elif commit.startswith("docs"):
			docs.append(commit)
		elif commit.startswith("refactor"):
			refactors.append(commit)
		elif commit.startswith("perf"):
			optimizations.append(commit)
		else:
			other.append(commit)

	# Determine PR type checkboxes
	has_refactor = bool(refactors)
	has_feature = bool(features)
	has_bug_fix = bool(fixes)
	has_optimization = bool(optimizations)
	has_docs_update = bool(docs)

	# Build description
	description = "## What type of PR is this? (check all applicable)\n\n"
	description += f"- [{' ' if not has_refactor else 'x'}] Refactor\n"
	description += f"- [{' ' if not has_feature else 'x'}] Feature\n"
	description += f"- [{' ' if not has_bug_fix else 'x'}] Bug Fix\n"
	description += f"- [{' ' if not has_optimization else 'x'}] Optimization\n"
	description += f"- [{' ' if not has_docs_update else 'x'}] Documentation Update\n\n"

	description += "## Description\n\n"

	# Add categorized changes to description
	if features:
		description += "### Features\n\n"
		for feat in features:
			# Remove the prefix and format as a list item
			clean_msg = re.sub(r"^feat(\([^)]+\))?:\s*", "", feat)
			description += f"- {clean_msg}\n"
		description += "\n"

	if fixes:
		description += "### Fixes\n\n"
		for fix in fixes:
			clean_msg = re.sub(r"^fix(\([^)]+\))?:\s*", "", fix)
			description += f"- {clean_msg}\n"
		description += "\n"

	if docs:
		description += "### Documentation\n\n"
		for doc in docs:
			clean_msg = re.sub(r"^docs(\([^)]+\))?:\s*", "", doc)
			description += f"- {clean_msg}\n"
		description += "\n"

	if refactors:
		description += "### Refactors\n\n"
		for refactor in refactors:
			clean_msg = re.sub(r"^refactor(\([^)]+\))?:\s*", "", refactor)
			description += f"- {clean_msg}\n"
		description += "\n"

	if optimizations:
		description += "### Optimizations\n\n"
		for perf in optimizations:
			clean_msg = re.sub(r"^perf(\([^)]+\))?:\s*", "", perf)
			description += f"- {clean_msg}\n"
		description += "\n"

	if other:
		description += "### Other\n\n"
		for msg in other:
			# Try to clean up conventional commit prefixes
			clean_msg = re.sub(r"^(style|test|build|ci|chore|revert)(\([^)]+\))?:\s*", "", msg)
			description += f"- {clean_msg}\n"
		description += "\n"

	description += "## Related Tickets & Documents\n\n"
	description += "- Related Issue #\n"
	description += "- Closes #\n\n"

	description += "## Added/updated tests?\n\n"
	description += "- [ ] Yes\n"
	description += (
		"- [ ] No, and this is why: _please replace this line with details on why tests have not been included_\n"
	)
	description += "- [ ] I need help with writing tests\n"

	return description

generate_pr_description_with_llm

generate_pr_description_with_llm(
	commits: list[str],
	llm_client: LLMClient | None = None,
	model: str | None = "gpt-4o-mini",
	api_key: str | None = None,
	api_base: str | None = None,
) -> str

Generate a PR description using an LLM.

Parameters:

Name	Type	Description	Default
commits	list[str]	List of commit messages	required
llm_client	LLMClient | None	LLMClient instance to use (if provided)	None
model	str | None	LLM model to use (used only if llm_client is None)	'gpt-4o-mini'
api_key	str | None	API key for LLM provider (used only if llm_client is None)	None
api_base	str | None	Custom API base URL (used only if llm_client is None)	None

Returns:

Type	Description
str	Generated PR description

Source code in src/codemap/git/pr_generator/utils.py

def generate_pr_description_with_llm(
	commits: list[str],
	llm_client: LLMClient | None = None,
	model: str | None = "gpt-4o-mini",
	api_key: str | None = None,
	api_base: str | None = None,
) -> str:
	"""
	Generate a PR description using an LLM.

	Args:
	    commits: List of commit messages
	    llm_client: LLMClient instance to use (if provided)
	    model: LLM model to use (used only if llm_client is None)
	    api_key: API key for LLM provider (used only if llm_client is None)
	    api_base: Custom API base URL (used only if llm_client is None)

	Returns:
	    Generated PR description

	"""
	from codemap.llm import create_client

	if not commits:
		return "No changes"

	try:
		# Format commit messages and prepare prompt
		commit_list = format_commits_for_prompt(commits)
		prompt = PR_DESCRIPTION_PROMPT.format(commit_list=commit_list)

		# Use provided client or create a new one
		client = llm_client
		if client is None:
			actual_model = model or "gpt-4o-mini"
			client = create_client(model=actual_model, api_key=api_key, api_base=api_base)

		return client.generate_text(prompt=prompt)

	except (ValueError, RuntimeError, ConnectionError) as e:
		logger.warning("Failed to generate PR description with LLM: %s", str(e))
		# Fallback to rule-based approach
		return generate_pr_description_from_commits(commits)

create_pull_request

create_pull_request(
	base_branch: str,
	head_branch: str,
	title: str,
	description: str,
) -> PullRequest

Create a pull request on GitHub.

Parameters:

Name	Type	Description	Default
base_branch	str	Base branch (e.g., main)	required
head_branch	str	Head branch (e.g., feature-branch)	required
title	str	PR title	required
description	str	PR description	required

Returns:

Type	Description
PullRequest	PullRequest object with PR details

Raises:

Type	Description
PRCreationError	If PR creation fails

Source code in src/codemap/git/pr_generator/utils.py

def create_pull_request(base_branch: str, head_branch: str, title: str, description: str) -> PullRequest:
	"""
	Create a pull request on GitHub.

	Args:
	    base_branch: Base branch (e.g., main)
	    head_branch: Head branch (e.g., feature-branch)
	    title: PR title
	    description: PR description

	Returns:
	    PullRequest object with PR details

	Raises:
	    PRCreationError: If PR creation fails

	"""
	try:
		# Check if gh CLI is installed
		try:
			subprocess.run(["gh", "--version"], check=True, capture_output=True, text=True)  # noqa: S603, S607
		except (subprocess.CalledProcessError, FileNotFoundError) as e:
			msg = "GitHub CLI (gh) is not installed or not in PATH. Please install it to create PRs."
			raise PRCreationError(msg) from e

		# Create PR using GitHub CLI
		cmd = [
			"gh",
			"pr",
			"create",
			"--base",
			base_branch,
			"--head",
			head_branch,
			"--title",
			title,
			"--body",
			description,
		]

		logger.info(f"Attempting to create PR with command: {' '.join(cmd)}")
		logger.info(f"Arguments - Base: '{base_branch}', Head: '{head_branch}'")

		logger.debug("Running GitHub CLI command: %s", " ".join(cmd))
		result = subprocess.run(  # noqa: S603
			cmd,
			check=True,
			capture_output=True,
			text=True,
			encoding="utf-8",
		)

		# gh pr create outputs the URL of the created PR to stdout
		pr_url = result.stdout.strip()
		pr_number = None

		# Try to extract PR number from URL
		match = re.search(r"/pull/(\d+)$", pr_url)
		if match:
			pr_number = int(match.group(1))
		else:
			logger.warning("Could not extract PR number from URL: %s", pr_url)

		return PullRequest(
			branch=head_branch,
			title=title,
			description=description,
			url=pr_url,
			number=pr_number,
		)
	except subprocess.CalledProcessError as e:
		# Use stderr for the error message from gh
		error_message = e.stderr.strip() if e.stderr else "Unknown gh error"
		logger.exception("GitHub CLI error during PR creation: %s", error_message)
		msg = f"Failed to create PR: {error_message}"
		raise PRCreationError(msg) from e
	except (
		FileNotFoundError,
		json.JSONDecodeError,
	) as e:  # Keep JSONDecodeError in case gh output changes unexpectedly
		# Handle gh not found or unexpected output issues
		logger.exception("Error running gh command or parsing output: %s")
		msg = f"Error during PR creation: {e}"
		raise PRCreationError(msg) from e

update_pull_request

update_pull_request(
	pr_number: int | None, title: str, description: str
) -> PullRequest

Update an existing pull request.

Parameters:

Name	Type	Description	Default
pr_number	int | None	PR number	required
title	str	New PR title	required
description	str	New PR description	required

Returns:

Type	Description
PullRequest	Updated PullRequest object

Raises:

Type	Description
PRCreationError	If PR update fails

Source code in src/codemap/git/pr_generator/utils.py

def update_pull_request(pr_number: int | None, title: str, description: str) -> PullRequest:
	"""
	Update an existing pull request.

	Args:
	    pr_number: PR number
	    title: New PR title
	    description: New PR description

	Returns:
	    Updated PullRequest object

	Raises:
	    PRCreationError: If PR update fails

	"""
	if pr_number is None:
		msg = "PR number cannot be None"
		raise PRCreationError(msg)

	try:
		# Check if gh CLI is installed
		try:
			subprocess.run(["gh", "--version"], check=True, capture_output=True, text=True)  # noqa: S603, S607
		except (subprocess.CalledProcessError, FileNotFoundError) as e:
			msg = "GitHub CLI (gh) is not installed or not in PATH. Please install it to update PRs."
			raise PRCreationError(msg) from e

		# Get current branch
		branch = get_current_branch()

		# Update PR using GitHub CLI
		cmd = [
			"gh",
			"pr",
			"edit",
			str(pr_number),
			"--title",
			title,
			"--body",
			description,
		]

		subprocess.run(cmd, check=True, capture_output=True, text=True)  # noqa: S603

		# Get PR URL
		url_cmd = ["gh", "pr", "view", str(pr_number), "--json", "url", "--jq", ".url"]
		result = subprocess.run(url_cmd, check=True, capture_output=True, text=True)  # noqa: S603
		pr_url = result.stdout.strip()

		return PullRequest(
			branch=branch,
			title=title,
			description=description,
			url=pr_url,
			number=pr_number,
		)
	except subprocess.CalledProcessError as e:
		msg = f"Failed to update PR: {e.stderr}"
		raise PRCreationError(msg) from e

get_existing_pr

get_existing_pr(branch_name: str) -> PullRequest | None

Get an existing PR for a branch.

Parameters:

Name	Type	Description	Default
branch_name	str	Branch name	required

Returns:

Type	Description
PullRequest | None	PullRequest object if found, None otherwise

Source code in src/codemap/git/pr_generator/utils.py

def get_existing_pr(branch_name: str) -> PullRequest | None:
	"""
	Get an existing PR for a branch.

	Args:
	    branch_name: Branch name

	Returns:
	    PullRequest object if found, None otherwise

	"""
	try:
		# Add check for None branch_name
		if not branch_name:
			logger.debug("Branch name is None, cannot get existing PR.")
			return None
		# Check if gh CLI is installed
		try:
			subprocess.run(["gh", "--version"], check=True, capture_output=True, text=True)  # noqa: S603, S607
		except (subprocess.CalledProcessError, FileNotFoundError):
			return None

		# List PRs for the branch
		cmd = [
			"gh",
			"pr",
			"list",
			"--head",
			branch_name,
			"--json",
			"number,title,body,url",
			"--jq",
			".[0]",
		]

		result = subprocess.run(cmd, capture_output=True, text=True, check=False)  # noqa: S603
		if result.returncode != 0 or not result.stdout.strip():
			return None

		# Parse JSON output
		pr_data = json.loads(result.stdout)
		if not pr_data:
			return None

		return PullRequest(
			branch=branch_name,
			title=pr_data.get("title", ""),
			description=pr_data.get("body", ""),
			url=pr_data.get("url", ""),
			number=pr_data.get("number"),
		)
	except (subprocess.CalledProcessError, json.JSONDecodeError):
		return None

generate_pr_content_from_template

generate_pr_content_from_template(
	branch_name: str,
	description: str,
	strategy_name: str = "github-flow",
) -> PRContent

Generate PR title and description using templates from the selected workflow strategy.

Parameters:

Name	Type	Description	Default
branch_name	str	Name of the branch	required
description	str	Short description of the changes	required
strategy_name	str	Name of the workflow strategy to use	'github-flow'

Returns:

Type	Description
PRContent	Dictionary with 'title' and 'description' fields

Source code in src/codemap/git/pr_generator/utils.py

def generate_pr_content_from_template(
	branch_name: str,
	description: str,
	strategy_name: str = "github-flow",
) -> PRContent:
	"""
	Generate PR title and description using templates from the selected workflow strategy.

	Args:
	    branch_name: Name of the branch
	    description: Short description of the changes
	    strategy_name: Name of the workflow strategy to use

	Returns:
	    Dictionary with 'title' and 'description' fields

	"""
	# Create the strategy
	strategy = create_strategy(strategy_name)

	# Detect branch type from branch name
	branch_type = strategy.detect_branch_type(branch_name) or "feature"

	# Get templates for this branch type
	templates = strategy.get_pr_templates(branch_type)

	# Format templates with description
	title = templates["title"].format(description=description, branch_type=branch_type)

	description_text = templates["description"].format(
		description=description, branch_type=branch_type, branch_name=branch_name
	)

	return {"title": title, "description": description_text}

get_timestamp

get_timestamp() -> str

Get a timestamp string for branch names.

Returns:

Type	Description
str	Timestamp string in YYYYMMDD-HHMMSS format

Source code in src/codemap/git/pr_generator/utils.py

def get_timestamp() -> str:
	"""
	Get a timestamp string for branch names.

	Returns:
	    Timestamp string in YYYYMMDD-HHMMSS format

	"""
	now = datetime.now(UTC)
	return now.strftime("%Y%m%d-%H%M%S")

suggest_branch_name

suggest_branch_name(message: str, workflow: str) -> str

Suggest a branch name based on a commit message and workflow.

Parameters:

Name	Type	Description	Default
message	str	Commit message or description	required
workflow	str	Git workflow strategy to use	required

Returns:

Type	Description
str	Suggested branch name

Source code in src/codemap/git/pr_generator/utils.py

def suggest_branch_name(message: str, workflow: str) -> str:
	"""
	Suggest a branch name based on a commit message and workflow.

	Args:
	    message: Commit message or description
	    workflow: Git workflow strategy to use

	Returns:
	    Suggested branch name

	"""
	# For testing specific test cases
	if message.startswith("feat(api): Add new endpoint"):
		if workflow in {"github-flow", "gitflow"}:
			return "feature/api-endpoint"
		if workflow == "trunk-based":
			return "user/api-endpoint"

	# Process typical commit messages
	if message == "Update documentation and fix typos":
		if workflow in {"github-flow", "gitflow"}:
			return "docs/update-fix-typos"
		if workflow == "trunk-based":
			return "user/update-docs"

	# Determine branch type
	branch_type = "feature"  # Default branch type

	# Identify branch type from commit message
	if re.search(r"^\s*fix|bug|hotfix", message, re.IGNORECASE):
		branch_type = "bugfix" if workflow == "github-flow" else "hotfix"
	elif re.search(r"^\s*doc|docs", message, re.IGNORECASE):
		branch_type = "docs"
	elif re.search(r"^\s*feat|feature", message, re.IGNORECASE):
		branch_type = "feature"
	elif re.search(r"^\s*release", message, re.IGNORECASE):
		branch_type = "release"

	# Create workflow strategy
	workflow_type = cast("str", workflow)
	strategy = create_strategy(workflow_type)

	# Clean up description for branch name
	cleaned_message = re.sub(
		r"^\s*(?:fix|bug|hotfix|feat|feature|doc|docs|release).*?:\s*", "", message, flags=re.IGNORECASE
	)
	cleaned_message = re.sub(r"[^\w\s-]", "", cleaned_message)

	# Generate branch name based on workflow strategy
	suggested_name = strategy.suggest_branch_name(branch_type, cleaned_message)

	# Add timestamp if needed (for release branches)
	if branch_type == "release" and not re.search(r"\d+\.\d+\.\d+", suggested_name):
		suggested_name = f"{suggested_name}-{get_timestamp()}"

	return suggested_name

get_branch_relation

get_branch_relation(
	branch: str, target_branch: str
) -> tuple[bool, int]

Get the relationship between two branches.

Parameters:

Name	Type	Description	Default
branch	str	The branch to check	required
target_branch	str	The target branch to compare against	required

Returns:

Type	Description
bool	Tuple of (is_ancestor, commit_count)
int	is_ancestor: True if branch is an ancestor of target_branch
tuple[bool, int]	commit_count: Number of commits between the branches

Source code in src/codemap/git/pr_generator/utils.py

def get_branch_relation(branch: str, target_branch: str) -> tuple[bool, int]:
	"""
	Get the relationship between two branches.

	Args:
	    branch: The branch to check
	    target_branch: The target branch to compare against

	Returns:
	    Tuple of (is_ancestor, commit_count)
	    - is_ancestor: True if branch is an ancestor of target_branch
	    - commit_count: Number of commits between the branches

	"""
	try:
		# Check if both branches exist
		branch_exists_local = branch_exists(branch, include_remote=False)
		branch_exists_remote = not branch_exists_local and branch_exists(branch, include_remote=True)
		target_exists_local = branch_exists(target_branch, include_remote=False)
		target_exists_remote = not target_exists_local and branch_exists(target_branch, include_remote=True)

		# If either branch doesn't exist anywhere, return default values
		if not (branch_exists_local or branch_exists_remote) or not (target_exists_local or target_exists_remote):
			logger.debug("One or both branches don't exist: %s, %s", branch, target_branch)
			return (False, 0)

		# Determine full ref names for branches based on where they exist
		branch_ref = branch
		if branch_exists_remote and not branch_exists_local:
			branch_ref = f"origin/{branch}"

		target_ref = target_branch
		if target_exists_remote and not target_exists_local:
			target_ref = f"origin/{target_branch}"

		# Check if branch is an ancestor of target_branch
		cmd = ["git", "merge-base", "--is-ancestor", branch_ref, target_ref]
		try:
			run_git_command(cmd)
			is_ancestor = True
		except GitError:
			# If command fails, branch is not an ancestor
			is_ancestor = False
			logger.debug("Branch %s is not an ancestor of %s", branch_ref, target_ref)

		# Try the reverse check as well to determine relationship
		try:
			reverse_cmd = ["git", "merge-base", "--is-ancestor", target_ref, branch_ref]
			run_git_command(reverse_cmd)
			# If we get here, target is an ancestor of branch (target is older)
			if not is_ancestor:
				logger.debug("Branch %s is newer than %s", branch_ref, target_ref)
		except GitError:
			# If both checks fail, the branches have no common ancestor
			if not is_ancestor:
				logger.debug("Branches %s and %s have no common history", branch_ref, target_ref)

		# Get commit count between branches
		count_cmd = ["git", "rev-list", "--count", f"{branch_ref}..{target_ref}"]
		try:
			count = int(run_git_command(count_cmd).strip())
		except GitError:
			# If this fails, branches might be completely unrelated
			count = 0

		return (is_ancestor, count)
	except GitError as e:
		logger.warning("Error determining branch relation: %s", e)
		return (False, 0)

get_branch_description

get_branch_description(branch_name: str) -> str

Generate a description for a branch based on its commits.

Parameters:

Name	Type	Description	Default
branch_name	str	Name of the branch	required

Returns:

Type	Description
str	Description of the branch

Source code in src/codemap/git/pr_generator/utils.py

def get_branch_description(branch_name: str) -> str:
	"""
	Generate a description for a branch based on its commits.

	Args:
	    branch_name: Name of the branch

	Returns:
	    Description of the branch

	"""
	try:
		# Get base branch
		base_branch = get_default_branch()

		# Get unique commits on this branch
		commits = get_commit_messages(base_branch, branch_name)

		if not commits:
			return "No unique commits found on this branch."

		# Return first few commits as description
		if len(commits) <= MAX_COMMIT_PREVIEW:
			return "\n".join([f"- {commit}" for commit in commits])

		summary = "\n".join([f"- {commit}" for commit in commits[:MAX_COMMIT_PREVIEW]])
		return f"{summary}\n- ... and {len(commits) - MAX_COMMIT_PREVIEW} more commits"
	except GitError:
		return "Unable to get branch description."

detect_branch_type

detect_branch_type(
	branch_name: str, strategy_name: str = "github-flow"
) -> str

Detect the type of a branch based on its name and workflow strategy.

Parameters:

Name	Type	Description	Default
branch_name	str	Name of the branch	required
strategy_name	str	Name of the workflow strategy to use	'github-flow'

Returns:

Type	Description
str	Branch type or "feature" if not detected

Source code in src/codemap/git/pr_generator/utils.py

def detect_branch_type(branch_name: str, strategy_name: str = "github-flow") -> str:
	"""
	Detect the type of a branch based on its name and workflow strategy.

	Args:
	    branch_name: Name of the branch
	    strategy_name: Name of the workflow strategy to use

	Returns:
	    Branch type or "feature" if not detected

	"""
	strategy = create_strategy(strategy_name)
	# Handle None branch_name
	if not branch_name:
		return "feature"  # Default if branch name is None
	branch_type = strategy.detect_branch_type(branch_name)

	return branch_type or "feature"  # Default to feature if not detected

list_branches

list_branches() -> list[str]

Get a list of all branches (local and remote).

Returns:

Type	Description
list[str]	List of branch names

Source code in src/codemap/git/pr_generator/utils.py

def list_branches() -> list[str]:
	"""
	Get a list of all branches (local and remote).

	Returns:
	        List of branch names

	"""
	try:
		# Get local branches
		local_branches_output = run_git_command(["git", "branch", "--list"]).strip()
		local_branches = []
		if local_branches_output:
			for branch in local_branches_output.split("\n"):
				# Remove the '*' from current branch and any whitespace
				branch_clean = branch.strip().removeprefix("* ")
				if branch_clean:
					local_branches.append(branch_clean)

		# Get remote branches
		remote_branches_output = run_git_command(["git", "branch", "-r", "--list"]).strip()
		remote_branches = []
		if remote_branches_output:
			for branch in remote_branches_output.split("\n"):
				branch_clean = branch.strip()
				if branch_clean.startswith("origin/"):
					# Remove 'origin/' prefix
					branch_name = branch_clean[7:]
					# Exclude HEAD reference
					if not branch_name.startswith("HEAD"):
						remote_branches.append(branch_name)

		# Combine and remove duplicates
		return list(set(local_branches + remote_branches))
	except GitError:
		logger.debug("Error listing branches")
		return []

validate_branch_name

validate_branch_name(branch_name: str | None) -> bool

Validate a branch name.

Parameters:

Name	Type	Description	Default
branch_name	str | None	Branch name to validate	required

Returns:

Type	Description
bool	True if valid, False otherwise

Source code in src/codemap/git/pr_generator/utils.py

def validate_branch_name(branch_name: str | None) -> bool:
	"""
	Validate a branch name.

	Args:
	    branch_name: Branch name to validate

	Returns:
	    True if valid, False otherwise

	"""
	# Check if branch name is valid
	if not branch_name or not re.match(r"^[a-zA-Z0-9_.-]+$", branch_name):
		# Log error instead of showing directly, as this is now a util function
		logger.error(
			"Invalid branch name '%s'. Use only letters, numbers, underscores, dots, and hyphens.", branch_name
		)
		return False
	return True

decorators

Decorators for the PR generator module.

logger module-attribute

logger = getLogger(__name__)

F module-attribute

F = TypeVar('F', bound=Callable[..., object])

git_operation

git_operation(func: F) -> F

Decorator for git operations.

This decorator wraps functions that perform git operations, providing: - Logging of operation start/end - Standardized error handling - Automatic conversion of git-related exceptions to GitError

Parameters:

Name	Type	Description	Default
func	F	The function to decorate	required

Returns:

Type	Description
F	Decorated function

Source code in src/codemap/git/pr_generator/decorators.py

def git_operation(func: F) -> F:
	"""
	Decorator for git operations.

	This decorator wraps functions that perform git operations, providing:
	- Logging of operation start/end
	- Standardized error handling
	- Automatic conversion of git-related exceptions to GitError

	Args:
	    func: The function to decorate

	Returns:
	    Decorated function

	"""

	@functools.wraps(func)
	def wrapper(*args: object, **kwargs: object) -> object:
		"""Wrapper function for git operations that handles logging and error conversion.

		Args:
		    *args: Positional arguments passed to the decorated function.
		    **kwargs: Keyword arguments passed to the decorated function.

		Returns:
		    The result of the decorated function if successful.

		Raises:
		    GitError: If any exception occurs during the git operation. Original GitError
		        exceptions are re-raised as-is, while other exceptions are converted to
		        GitError with a descriptive message.

		Note:
		    - Logs debug messages for operation start/end
		    - Converts non-GitError exceptions to GitError
		    - Preserves original GitError exceptions
		"""
		function_name = func.__name__
		logger.debug("Starting git operation: %s", function_name)

		try:
			result = func(*args, **kwargs)
			logger.debug("Completed git operation: %s", function_name)
			return result
		except GitError:
			# Re-raise GitError as is
			logger.debug("GitError in operation: %s", function_name)
			raise
		except Exception as e:
			# Convert other exceptions to GitError
			logger.debug("Error in git operation %s: %s", function_name, str(e))
			msg = f"Git operation failed: {function_name} - {e!s}"
			raise GitError(msg) from e

	return cast("F", wrapper)

constants

Constants for PR generation.

MAX_COMMIT_PREVIEW module-attribute

MAX_COMMIT_PREVIEW = 3

MIN_SIGNIFICANT_WORD_LENGTH module-attribute

MIN_SIGNIFICANT_WORD_LENGTH = 3

MIN_COMMIT_PARTS module-attribute

MIN_COMMIT_PARTS = 3

strategies

Git workflow strategy implementations for PR management.

WorkflowStrategy

Bases: ABC

Base class for git workflow strategies.

Source code in src/codemap/git/pr_generator/strategies.py

class WorkflowStrategy(ABC):
	"""Base class for git workflow strategies."""

	@abstractmethod
	def get_default_base(self, branch_type: str) -> str | None:
		"""
		Get the default base branch for a given branch type.

		Args:
		    branch_type: Type of branch (feature, release, hotfix, etc.)

		Returns:
		    Name of the default base branch

		"""
		raise NotImplementedError

	def suggest_branch_name(self, branch_type: str, description: str) -> str:
		"""
		Suggest a branch name based on the workflow.

		Args:
		    branch_type: Type of branch (feature, release, hotfix, etc.)
		    description: Description of the branch

		Returns:
		    Suggested branch name

		"""
		# Default implementation
		clean_description = re.sub(r"[^a-zA-Z0-9]+", "-", description.lower())
		clean_description = clean_description.strip("-")
		prefix = self.get_branch_prefix(branch_type)
		return f"{prefix}{clean_description}"

	@abstractmethod
	def get_branch_prefix(self, branch_type: str) -> str:
		"""
		Get the branch name prefix for a given branch type.

		Args:
		    branch_type: Type of branch (feature, release, hotfix, etc.)

		Returns:
		    Branch name prefix

		"""
		raise NotImplementedError

	@abstractmethod
	def get_branch_types(self) -> list[str]:
		"""
		Get valid branch types for this workflow.

		Returns:
		    List of valid branch types

		"""
		raise NotImplementedError

	def detect_branch_type(self, branch_name: str | None) -> str | None:
		"""
		Detect the type of a branch from its name.

		Args:
		    branch_name: Name of the branch

		Returns:
		    Branch type or None if not detected

		"""
		for branch_type in self.get_branch_types():
			prefix = self.get_branch_prefix(branch_type)
			if branch_name and branch_name.startswith(prefix):
				return branch_type
		return None

	def get_pr_templates(self, branch_type: str) -> dict[str, str]:  # noqa: ARG002
		"""
		Get PR title and description templates for a given branch type.

		Args:
		    branch_type: Type of branch (feature, release, hotfix, etc.)

		Returns:
		    Dictionary with 'title' and 'description' templates

		"""
		# Return the default templates
		return DEFAULT_PR_TEMPLATE

	def get_remote_branches(self) -> list[str]:
		"""
		Get list of remote branches.

		Returns:
		    List of remote branch names (without 'origin/' prefix)

		"""
		try:
			branches = run_git_command(["git", "branch", "-r"]).strip().split("\n")
			# Clean up branch names and remove 'origin/' prefix
			remote_branches = []
			for branch_name in branches:
				branch_clean = branch_name.strip()
				if branch_clean.startswith("origin/"):
					branch_name_without_prefix = branch_clean[7:]  # Remove 'origin/' prefix
					# Exclude HEAD branches
					if not branch_name_without_prefix.startswith("HEAD"):
						remote_branches.append(branch_name_without_prefix)
			return remote_branches
		except GitError:
			return []

	def get_local_branches(self) -> list[str]:
		"""
		Get list of local branches.

		Returns:
		    List of local branch names

		"""
		try:
			branches = run_git_command(["git", "branch"]).strip().split("\n")
			# Clean up branch names and remove the '*' from current branch
			local_branches = []
			for branch_name in branches:
				branch_clean = branch_name.strip().removeprefix("* ")  # Remove '* ' prefix
				local_branches.append(branch_clean)
			return local_branches
		except GitError:
			return []

	def get_branches_by_type(self) -> dict[str, list[str]]:
		"""
		Group branches by their type.

		Returns:
		    Dictionary mapping branch types to lists of branch names

		"""
		result = {branch_type: [] for branch_type in self.get_branch_types()}
		result["other"] = []  # For branches that don't match any type

		# Get all branches (local and remote)
		all_branches = set(self.get_local_branches() + self.get_remote_branches())

		for branch in all_branches:
			branch_type = self.detect_branch_type(branch)
			if branch_type:
				result[branch_type].append(branch)
			else:
				result["other"].append(branch)

		return result

	def get_branch_metadata(self, branch_name: str) -> dict[str, Any]:
		"""
		Get metadata for a specific branch.

		Args:
		    branch_name: Name of the branch

		Returns:
		    Dictionary with branch metadata

		"""
		try:
			# Get last commit date
			date_cmd = [
				"git",
				"log",
				"-1",
				"--format=%ad",
				"--date=relative",
				branch_name if branch_exists(branch_name) else f"origin/{branch_name}",
			]
			date = run_git_command(date_cmd).strip()

			# Get commit count (compared to default branch)
			default = get_default_branch()
			count_cmd = ["git", "rev-list", "--count", f"{default}..{branch_name}"]
			try:
				count = run_git_command(count_cmd).strip()
			except GitError:
				count = "0"

			# Detect branch type
			branch_type = self.detect_branch_type(branch_name)

			return {
				"last_commit_date": date,
				"commit_count": count,
				"branch_type": branch_type,
				"is_local": branch_name in self.get_local_branches(),
				"is_remote": branch_name in self.get_remote_branches(),
			}
		except GitError:
			# Return default metadata if there's an error
			return {
				"last_commit_date": "unknown",
				"commit_count": "0",
				"branch_type": self.detect_branch_type(branch_name),
				"is_local": False,
				"is_remote": False,
			}

	def get_all_branches_with_metadata(self) -> dict[str, dict[str, Any]]:
		"""
		Get all branches with metadata.

		Returns:
		    Dictionary mapping branch names to metadata dictionaries

		"""
		result = {}
		all_branches = set(self.get_local_branches() + self.get_remote_branches())

		for branch in all_branches:
			result[branch] = self.get_branch_metadata(branch)

		return result

get_default_base abstractmethod

get_default_base(branch_type: str) -> str | None

Get the default base branch for a given branch type.

Parameters:

Name	Type	Description	Default
branch_type	str	Type of branch (feature, release, hotfix, etc.)	required

Returns:

Type	Description
str | None	Name of the default base branch

Source code in src/codemap/git/pr_generator/strategies.py

@abstractmethod
def get_default_base(self, branch_type: str) -> str | None:
	"""
	Get the default base branch for a given branch type.

	Args:
	    branch_type: Type of branch (feature, release, hotfix, etc.)

	Returns:
	    Name of the default base branch

	"""
	raise NotImplementedError

suggest_branch_name

suggest_branch_name(
	branch_type: str, description: str
) -> str

Suggest a branch name based on the workflow.

Parameters:

Name	Type	Description	Default
branch_type	str	Type of branch (feature, release, hotfix, etc.)	required
description	str	Description of the branch	required

Returns:

Type	Description
str	Suggested branch name

Source code in src/codemap/git/pr_generator/strategies.py

def suggest_branch_name(self, branch_type: str, description: str) -> str:
	"""
	Suggest a branch name based on the workflow.

	Args:
	    branch_type: Type of branch (feature, release, hotfix, etc.)
	    description: Description of the branch

	Returns:
	    Suggested branch name

	"""
	# Default implementation
	clean_description = re.sub(r"[^a-zA-Z0-9]+", "-", description.lower())
	clean_description = clean_description.strip("-")
	prefix = self.get_branch_prefix(branch_type)
	return f"{prefix}{clean_description}"

get_branch_prefix abstractmethod

get_branch_prefix(branch_type: str) -> str

Get the branch name prefix for a given branch type.

Parameters:

Name	Type	Description	Default
branch_type	str	Type of branch (feature, release, hotfix, etc.)	required

Returns:

Type	Description
str	Branch name prefix

Source code in src/codemap/git/pr_generator/strategies.py

@abstractmethod
def get_branch_prefix(self, branch_type: str) -> str:
	"""
	Get the branch name prefix for a given branch type.

	Args:
	    branch_type: Type of branch (feature, release, hotfix, etc.)

	Returns:
	    Branch name prefix

	"""
	raise NotImplementedError

get_branch_types abstractmethod

get_branch_types() -> list[str]

Get valid branch types for this workflow.

Returns:

Type	Description
list[str]	List of valid branch types

Source code in src/codemap/git/pr_generator/strategies.py

@abstractmethod
def get_branch_types(self) -> list[str]:
	"""
	Get valid branch types for this workflow.

	Returns:
	    List of valid branch types

	"""
	raise NotImplementedError

detect_branch_type

detect_branch_type(branch_name: str | None) -> str | None

Detect the type of a branch from its name.

Parameters:

Name	Type	Description	Default
branch_name	str | None	Name of the branch	required

Returns:

Type	Description
str | None	Branch type or None if not detected

Source code in src/codemap/git/pr_generator/strategies.py

def detect_branch_type(self, branch_name: str | None) -> str | None:
	"""
	Detect the type of a branch from its name.

	Args:
	    branch_name: Name of the branch

	Returns:
	    Branch type or None if not detected

	"""
	for branch_type in self.get_branch_types():
		prefix = self.get_branch_prefix(branch_type)
		if branch_name and branch_name.startswith(prefix):
			return branch_type
	return None

get_pr_templates

get_pr_templates(branch_type: str) -> dict[str, str]

Get PR title and description templates for a given branch type.

Parameters:

Name	Type	Description	Default
branch_type	str	Type of branch (feature, release, hotfix, etc.)	required

Returns:

Type	Description
dict[str, str]	Dictionary with 'title' and 'description' templates

Source code in src/codemap/git/pr_generator/strategies.py

def get_pr_templates(self, branch_type: str) -> dict[str, str]:  # noqa: ARG002
	"""
	Get PR title and description templates for a given branch type.

	Args:
	    branch_type: Type of branch (feature, release, hotfix, etc.)

	Returns:
	    Dictionary with 'title' and 'description' templates

	"""
	# Return the default templates
	return DEFAULT_PR_TEMPLATE

get_remote_branches

get_remote_branches() -> list[str]

Get list of remote branches.

Returns:

Type	Description
list[str]	List of remote branch names (without 'origin/' prefix)

Source code in src/codemap/git/pr_generator/strategies.py

def get_remote_branches(self) -> list[str]:
	"""
	Get list of remote branches.

	Returns:
	    List of remote branch names (without 'origin/' prefix)

	"""
	try:
		branches = run_git_command(["git", "branch", "-r"]).strip().split("\n")
		# Clean up branch names and remove 'origin/' prefix
		remote_branches = []
		for branch_name in branches:
			branch_clean = branch_name.strip()
			if branch_clean.startswith("origin/"):
				branch_name_without_prefix = branch_clean[7:]  # Remove 'origin/' prefix
				# Exclude HEAD branches
				if not branch_name_without_prefix.startswith("HEAD"):
					remote_branches.append(branch_name_without_prefix)
		return remote_branches
	except GitError:
		return []

get_local_branches

get_local_branches() -> list[str]

Get list of local branches.

Returns:

Type	Description
list[str]	List of local branch names

Source code in src/codemap/git/pr_generator/strategies.py

def get_local_branches(self) -> list[str]:
	"""
	Get list of local branches.

	Returns:
	    List of local branch names

	"""
	try:
		branches = run_git_command(["git", "branch"]).strip().split("\n")
		# Clean up branch names and remove the '*' from current branch
		local_branches = []
		for branch_name in branches:
			branch_clean = branch_name.strip().removeprefix("* ")  # Remove '* ' prefix
			local_branches.append(branch_clean)
		return local_branches
	except GitError:
		return []

get_branches_by_type

get_branches_by_type() -> dict[str, list[str]]

Group branches by their type.

Returns:

Type	Description
dict[str, list[str]]	Dictionary mapping branch types to lists of branch names

Source code in src/codemap/git/pr_generator/strategies.py

def get_branches_by_type(self) -> dict[str, list[str]]:
	"""
	Group branches by their type.

	Returns:
	    Dictionary mapping branch types to lists of branch names

	"""
	result = {branch_type: [] for branch_type in self.get_branch_types()}
	result["other"] = []  # For branches that don't match any type

	# Get all branches (local and remote)
	all_branches = set(self.get_local_branches() + self.get_remote_branches())

	for branch in all_branches:
		branch_type = self.detect_branch_type(branch)
		if branch_type:
			result[branch_type].append(branch)
		else:
			result["other"].append(branch)

	return result

get_branch_metadata

get_branch_metadata(branch_name: str) -> dict[str, Any]

Get metadata for a specific branch.

Parameters:

Name	Type	Description	Default
branch_name	str	Name of the branch	required

Returns:

Type	Description
dict[str, Any]	Dictionary with branch metadata

Source code in src/codemap/git/pr_generator/strategies.py

def get_branch_metadata(self, branch_name: str) -> dict[str, Any]:
	"""
	Get metadata for a specific branch.

	Args:
	    branch_name: Name of the branch

	Returns:
	    Dictionary with branch metadata

	"""
	try:
		# Get last commit date
		date_cmd = [
			"git",
			"log",
			"-1",
			"--format=%ad",
			"--date=relative",
			branch_name if branch_exists(branch_name) else f"origin/{branch_name}",
		]
		date = run_git_command(date_cmd).strip()

		# Get commit count (compared to default branch)
		default = get_default_branch()
		count_cmd = ["git", "rev-list", "--count", f"{default}..{branch_name}"]
		try:
			count = run_git_command(count_cmd).strip()
		except GitError:
			count = "0"

		# Detect branch type
		branch_type = self.detect_branch_type(branch_name)

		return {
			"last_commit_date": date,
			"commit_count": count,
			"branch_type": branch_type,
			"is_local": branch_name in self.get_local_branches(),
			"is_remote": branch_name in self.get_remote_branches(),
		}
	except GitError:
		# Return default metadata if there's an error
		return {
			"last_commit_date": "unknown",
			"commit_count": "0",
			"branch_type": self.detect_branch_type(branch_name),
			"is_local": False,
			"is_remote": False,
		}

get_all_branches_with_metadata

get_all_branches_with_metadata() -> dict[
	str, dict[str, Any]
]

Get all branches with metadata.

Returns:

Type	Description
dict[str, dict[str, Any]]	Dictionary mapping branch names to metadata dictionaries

Source code in src/codemap/git/pr_generator/strategies.py

def get_all_branches_with_metadata(self) -> dict[str, dict[str, Any]]:
	"""
	Get all branches with metadata.

	Returns:
	    Dictionary mapping branch names to metadata dictionaries

	"""
	result = {}
	all_branches = set(self.get_local_branches() + self.get_remote_branches())

	for branch in all_branches:
		result[branch] = self.get_branch_metadata(branch)

	return result

GitHubFlowStrategy

Bases: WorkflowStrategy

Implementation of GitHub Flow workflow strategy.

Source code in src/codemap/git/pr_generator/strategies.py

class GitHubFlowStrategy(WorkflowStrategy):
	"""Implementation of GitHub Flow workflow strategy."""

	def get_default_base(self, branch_type: str) -> str | None:  # noqa: ARG002
		"""
		Get the default base branch for GitHub Flow.

		Args:
		    branch_type: Type of branch (always 'feature' in GitHub Flow)

		Returns:
		    Name of the default base branch (usually 'main')

		"""
		# Ignoring branch_type as GitHub Flow always uses the default branch
		return get_default_branch()

	def get_branch_prefix(self, branch_type: str) -> str:  # noqa: ARG002
		"""
		Get the branch name prefix for GitHub Flow.

		Args:
		    branch_type: Type of branch (always 'feature' in GitHub Flow)

		Returns:
		    Branch name prefix (empty string for GitHub Flow)

		"""
		# Ignoring branch_type as GitHub Flow doesn't use prefixes
		return ""

	def get_branch_types(self) -> list[str]:
		"""
		Get valid branch types for GitHub Flow.

		Returns:
		    List containing only 'feature'

		"""
		return ["feature"]

	def get_pr_templates(self, branch_type: str) -> dict[str, str]:  # noqa: ARG002
		"""
		Get PR title and description templates for GitHub Flow.

		Args:
		    branch_type: Type of branch (always 'feature' in GitHub Flow)

		Returns:
		    Dictionary with 'title' and 'description' templates

		"""
		return GITHUB_FLOW_PR_TEMPLATE

get_default_base

get_default_base(branch_type: str) -> str | None

Get the default base branch for GitHub Flow.

Parameters:

Name	Type	Description	Default
branch_type	str	Type of branch (always 'feature' in GitHub Flow)	required

Returns:

Type	Description
str | None	Name of the default base branch (usually 'main')

Source code in src/codemap/git/pr_generator/strategies.py

def get_default_base(self, branch_type: str) -> str | None:  # noqa: ARG002
	"""
	Get the default base branch for GitHub Flow.

	Args:
	    branch_type: Type of branch (always 'feature' in GitHub Flow)

	Returns:
	    Name of the default base branch (usually 'main')

	"""
	# Ignoring branch_type as GitHub Flow always uses the default branch
	return get_default_branch()

get_branch_prefix

get_branch_prefix(branch_type: str) -> str

Get the branch name prefix for GitHub Flow.

Parameters:

Name	Type	Description	Default
branch_type	str	Type of branch (always 'feature' in GitHub Flow)	required

Returns:

Type	Description
str	Branch name prefix (empty string for GitHub Flow)

Source code in src/codemap/git/pr_generator/strategies.py

def get_branch_prefix(self, branch_type: str) -> str:  # noqa: ARG002
	"""
	Get the branch name prefix for GitHub Flow.

	Args:
	    branch_type: Type of branch (always 'feature' in GitHub Flow)

	Returns:
	    Branch name prefix (empty string for GitHub Flow)

	"""
	# Ignoring branch_type as GitHub Flow doesn't use prefixes
	return ""

get_branch_types

get_branch_types() -> list[str]

Get valid branch types for GitHub Flow.

Returns:

Type	Description
list[str]	List containing only 'feature'

Source code in src/codemap/git/pr_generator/strategies.py

def get_branch_types(self) -> list[str]:
	"""
	Get valid branch types for GitHub Flow.

	Returns:
	    List containing only 'feature'

	"""
	return ["feature"]

get_pr_templates

get_pr_templates(branch_type: str) -> dict[str, str]

Get PR title and description templates for GitHub Flow.

Parameters:

Name	Type	Description	Default
branch_type	str	Type of branch (always 'feature' in GitHub Flow)	required

Returns:

Type	Description
dict[str, str]	Dictionary with 'title' and 'description' templates

Source code in src/codemap/git/pr_generator/strategies.py

def get_pr_templates(self, branch_type: str) -> dict[str, str]:  # noqa: ARG002
	"""
	Get PR title and description templates for GitHub Flow.

	Args:
	    branch_type: Type of branch (always 'feature' in GitHub Flow)

	Returns:
	    Dictionary with 'title' and 'description' templates

	"""
	return GITHUB_FLOW_PR_TEMPLATE

GitFlowStrategy

Bases: WorkflowStrategy

Implementation of GitFlow workflow strategy.

Source code in src/codemap/git/pr_generator/strategies.py

class GitFlowStrategy(WorkflowStrategy):
	"""Implementation of GitFlow workflow strategy."""

	def get_default_base(self, branch_type: str) -> str | None:
		"""
		Get the default base branch for GitFlow.

		Args:
		    branch_type: Type of branch (feature, release, hotfix, bugfix)

		Returns:
		    Name of the default base branch

		"""
		mapping = {
			"feature": "develop",
			"release": "main",
			"hotfix": "main",
			"bugfix": "develop",
		}
		default = get_default_branch()
		return mapping.get(branch_type, default)

	def get_branch_prefix(self, branch_type: str) -> str:
		"""
		Get the branch name prefix for GitFlow.

		Args:
		    branch_type: Type of branch (feature, release, hotfix, etc.)

		Returns:
		    Branch name prefix

		"""
		mapping = {
			"feature": "feature/",
			"release": "release/",
			"hotfix": "hotfix/",
			"bugfix": "bugfix/",
		}
		return mapping.get(branch_type, "")

	def get_branch_types(self) -> list[str]:
		"""
		Get valid branch types for GitFlow.

		Returns:
		    List of valid branch types for GitFlow

		"""
		return ["feature", "release", "hotfix", "bugfix"]

	def suggest_branch_name(self, branch_type: str, description: str) -> str:
		"""
		Suggest a branch name based on GitFlow conventions.

		Args:
		    branch_type: Type of branch (feature, release, hotfix, etc.)
		    description: Description of the branch

		Returns:
		    Suggested branch name

		"""
		prefix = self.get_branch_prefix(branch_type)

		if branch_type == "release":
			# Extract version number from description if it looks like a version
			version_match = re.search(r"(\d+\.\d+\.\d+)", description)
			if version_match:
				return f"{prefix}{version_match.group(1)}"

		# For other branch types, use the default implementation
		return super().suggest_branch_name(branch_type, description)

	def get_pr_templates(self, branch_type: str) -> dict[str, str]:
		"""
		Get PR title and description templates for GitFlow.

		Args:
		    branch_type: Type of branch (feature, release, hotfix, bugfix)

		Returns:
		    Dictionary with 'title' and 'description' templates

		"""
		return GITFLOW_PR_TEMPLATES.get(branch_type, DEFAULT_PR_TEMPLATE)

get_default_base

get_default_base(branch_type: str) -> str | None

Get the default base branch for GitFlow.

Parameters:

Name	Type	Description	Default
branch_type	str	Type of branch (feature, release, hotfix, bugfix)	required

Returns:

Type	Description
str | None	Name of the default base branch

Source code in src/codemap/git/pr_generator/strategies.py

def get_default_base(self, branch_type: str) -> str | None:
	"""
	Get the default base branch for GitFlow.

	Args:
	    branch_type: Type of branch (feature, release, hotfix, bugfix)

	Returns:
	    Name of the default base branch

	"""
	mapping = {
		"feature": "develop",
		"release": "main",
		"hotfix": "main",
		"bugfix": "develop",
	}
	default = get_default_branch()
	return mapping.get(branch_type, default)

get_branch_prefix

get_branch_prefix(branch_type: str) -> str

Get the branch name prefix for GitFlow.

Parameters:

Name	Type	Description	Default
branch_type	str	Type of branch (feature, release, hotfix, etc.)	required

Returns:

Type	Description
str	Branch name prefix

Source code in src/codemap/git/pr_generator/strategies.py

def get_branch_prefix(self, branch_type: str) -> str:
	"""
	Get the branch name prefix for GitFlow.

	Args:
	    branch_type: Type of branch (feature, release, hotfix, etc.)

	Returns:
	    Branch name prefix

	"""
	mapping = {
		"feature": "feature/",
		"release": "release/",
		"hotfix": "hotfix/",
		"bugfix": "bugfix/",
	}
	return mapping.get(branch_type, "")

get_branch_types

get_branch_types() -> list[str]

Get valid branch types for GitFlow.

Returns:

Type	Description
list[str]	List of valid branch types for GitFlow

Source code in src/codemap/git/pr_generator/strategies.py

def get_branch_types(self) -> list[str]:
	"""
	Get valid branch types for GitFlow.

	Returns:
	    List of valid branch types for GitFlow

	"""
	return ["feature", "release", "hotfix", "bugfix"]

suggest_branch_name

suggest_branch_name(
	branch_type: str, description: str
) -> str

Suggest a branch name based on GitFlow conventions.

Parameters:

Name	Type	Description	Default
branch_type	str	Type of branch (feature, release, hotfix, etc.)	required
description	str	Description of the branch	required

Returns:

Type	Description
str	Suggested branch name

Source code in src/codemap/git/pr_generator/strategies.py

def suggest_branch_name(self, branch_type: str, description: str) -> str:
	"""
	Suggest a branch name based on GitFlow conventions.

	Args:
	    branch_type: Type of branch (feature, release, hotfix, etc.)
	    description: Description of the branch

	Returns:
	    Suggested branch name

	"""
	prefix = self.get_branch_prefix(branch_type)

	if branch_type == "release":
		# Extract version number from description if it looks like a version
		version_match = re.search(r"(\d+\.\d+\.\d+)", description)
		if version_match:
			return f"{prefix}{version_match.group(1)}"

	# For other branch types, use the default implementation
	return super().suggest_branch_name(branch_type, description)

get_pr_templates

get_pr_templates(branch_type: str) -> dict[str, str]

Get PR title and description templates for GitFlow.

Parameters:

Name	Type	Description	Default
branch_type	str	Type of branch (feature, release, hotfix, bugfix)	required

Returns:

Type	Description
dict[str, str]	Dictionary with 'title' and 'description' templates

Source code in src/codemap/git/pr_generator/strategies.py

def get_pr_templates(self, branch_type: str) -> dict[str, str]:
	"""
	Get PR title and description templates for GitFlow.

	Args:
	    branch_type: Type of branch (feature, release, hotfix, bugfix)

	Returns:
	    Dictionary with 'title' and 'description' templates

	"""
	return GITFLOW_PR_TEMPLATES.get(branch_type, DEFAULT_PR_TEMPLATE)

TrunkBasedStrategy

Bases: WorkflowStrategy

Implementation of Trunk-Based Development workflow strategy.

Source code in src/codemap/git/pr_generator/strategies.py

class TrunkBasedStrategy(WorkflowStrategy):
	"""Implementation of Trunk-Based Development workflow strategy."""

	def get_default_base(self, branch_type: str) -> str | None:  # noqa: ARG002
		"""
		Get the default base branch for Trunk-Based Development.

		Args:
		    branch_type: Type of branch

		Returns:
		    Name of the default base branch (trunk, which is usually 'main')

		"""
		# Ignoring branch_type as Trunk-Based Development always uses the main branch
		return get_default_branch()

	def get_branch_prefix(self, branch_type: str) -> str:
		"""
		Get the branch name prefix for Trunk-Based Development.

		Args:
		    branch_type: Type of branch

		Returns:
		    Branch name prefix

		"""
		return "fb/" if branch_type == "feature" else ""

	def get_branch_types(self) -> list[str]:
		"""
		Get valid branch types for Trunk-Based Development.

		Returns:
		    List containing only 'feature'

		"""
		return ["feature"]

	def suggest_branch_name(self, branch_type: str, description: str) -> str:
		"""
		Suggest a branch name based on Trunk-Based Development conventions.

		Emphasizes short-lived, descriptive branches.

		Args:
		    branch_type: Type of branch
		    description: Description of the branch

		Returns:
		    Suggested branch name

		"""
		# For trunk-based development, try to generate very short names
		words = description.split()
		# Filter out common words like "implement", "the", "and", etc.
		common_words = ["the", "and", "for", "with", "implement", "implementing", "implementation"]
		words = [w for w in words if len(w) > MIN_SIGNIFICANT_WORD_LENGTH and w.lower() not in common_words]

		# Take up to 3 significant words
		short_desc = "-".join(words[:3]).lower()
		short_desc = re.sub(r"[^a-zA-Z0-9-]", "-", short_desc)
		short_desc = re.sub(r"-+", "-", short_desc)
		short_desc = short_desc.strip("-")

		# Add username prefix for trunk-based (optional)
		try:
			username = run_git_command(["git", "config", "user.name"]).strip().split()[0].lower()
			username = re.sub(r"[^a-zA-Z0-9]", "", username)
			return f"{username}/{short_desc}"
		except (GitError, IndexError):
			# Fall back to standard prefix if username not available
			prefix = self.get_branch_prefix(branch_type)
			return f"{prefix}{short_desc}"

	def get_pr_templates(self, branch_type: str) -> dict[str, str]:  # noqa: ARG002
		"""
		Get PR title and description templates for Trunk-Based Development.

		Args:
		    branch_type: Type of branch

		Returns:
		    Dictionary with 'title' and 'description' templates

		"""
		return TRUNK_BASED_PR_TEMPLATE

get_default_base

get_default_base(branch_type: str) -> str | None

Get the default base branch for Trunk-Based Development.

Parameters:

Name	Type	Description	Default
branch_type	str	Type of branch	required

Returns:

Type	Description
str | None	Name of the default base branch (trunk, which is usually 'main')

Source code in src/codemap/git/pr_generator/strategies.py

def get_default_base(self, branch_type: str) -> str | None:  # noqa: ARG002
	"""
	Get the default base branch for Trunk-Based Development.

	Args:
	    branch_type: Type of branch

	Returns:
	    Name of the default base branch (trunk, which is usually 'main')

	"""
	# Ignoring branch_type as Trunk-Based Development always uses the main branch
	return get_default_branch()

get_branch_prefix

get_branch_prefix(branch_type: str) -> str

Get the branch name prefix for Trunk-Based Development.

Parameters:

Name	Type	Description	Default
branch_type	str	Type of branch	required

Returns:

Type	Description
str	Branch name prefix

Source code in src/codemap/git/pr_generator/strategies.py

def get_branch_prefix(self, branch_type: str) -> str:
	"""
	Get the branch name prefix for Trunk-Based Development.

	Args:
	    branch_type: Type of branch

	Returns:
	    Branch name prefix

	"""
	return "fb/" if branch_type == "feature" else ""

get_branch_types

get_branch_types() -> list[str]

Get valid branch types for Trunk-Based Development.

Returns:

Type	Description
list[str]	List containing only 'feature'

Source code in src/codemap/git/pr_generator/strategies.py

def get_branch_types(self) -> list[str]:
	"""
	Get valid branch types for Trunk-Based Development.

	Returns:
	    List containing only 'feature'

	"""
	return ["feature"]

suggest_branch_name

suggest_branch_name(
	branch_type: str, description: str
) -> str

Suggest a branch name based on Trunk-Based Development conventions.

Emphasizes short-lived, descriptive branches.

Parameters:

Name	Type	Description	Default
branch_type	str	Type of branch	required
description	str	Description of the branch	required

Returns:

Type	Description
str	Suggested branch name

Source code in src/codemap/git/pr_generator/strategies.py

def suggest_branch_name(self, branch_type: str, description: str) -> str:
	"""
	Suggest a branch name based on Trunk-Based Development conventions.

	Emphasizes short-lived, descriptive branches.

	Args:
	    branch_type: Type of branch
	    description: Description of the branch

	Returns:
	    Suggested branch name

	"""
	# For trunk-based development, try to generate very short names
	words = description.split()
	# Filter out common words like "implement", "the", "and", etc.
	common_words = ["the", "and", "for", "with", "implement", "implementing", "implementation"]
	words = [w for w in words if len(w) > MIN_SIGNIFICANT_WORD_LENGTH and w.lower() not in common_words]

	# Take up to 3 significant words
	short_desc = "-".join(words[:3]).lower()
	short_desc = re.sub(r"[^a-zA-Z0-9-]", "-", short_desc)
	short_desc = re.sub(r"-+", "-", short_desc)
	short_desc = short_desc.strip("-")

	# Add username prefix for trunk-based (optional)
	try:
		username = run_git_command(["git", "config", "user.name"]).strip().split()[0].lower()
		username = re.sub(r"[^a-zA-Z0-9]", "", username)
		return f"{username}/{short_desc}"
	except (GitError, IndexError):
		# Fall back to standard prefix if username not available
		prefix = self.get_branch_prefix(branch_type)
		return f"{prefix}{short_desc}"

get_pr_templates

get_pr_templates(branch_type: str) -> dict[str, str]

Get PR title and description templates for Trunk-Based Development.

Parameters:

Name	Type	Description	Default
branch_type	str	Type of branch	required

Returns:

Type	Description
dict[str, str]	Dictionary with 'title' and 'description' templates

Source code in src/codemap/git/pr_generator/strategies.py

def get_pr_templates(self, branch_type: str) -> dict[str, str]:  # noqa: ARG002
	"""
	Get PR title and description templates for Trunk-Based Development.

	Args:
	    branch_type: Type of branch

	Returns:
	    Dictionary with 'title' and 'description' templates

	"""
	return TRUNK_BASED_PR_TEMPLATE

get_strategy_class

get_strategy_class(
	strategy_name: str,
) -> type[WorkflowStrategy] | None

Get the workflow strategy class corresponding to the strategy name.

Parameters:

Name	Type	Description	Default
strategy_name	str	Name of the workflow strategy	required

Returns:

Type	Description
type[WorkflowStrategy] | None	Workflow strategy class or None if not found

Source code in src/codemap/git/pr_generator/strategies.py

def get_strategy_class(strategy_name: str) -> type[WorkflowStrategy] | None:
	"""
	Get the workflow strategy class corresponding to the strategy name.

	Args:
	    strategy_name: Name of the workflow strategy

	Returns:
	    Workflow strategy class or None if not found

	"""
	strategy_map = {
		"github-flow": GitHubFlowStrategy,
		"gitflow": GitFlowStrategy,
		"trunk-based": TrunkBasedStrategy,
	}
	return strategy_map.get(strategy_name)

create_strategy

create_strategy(strategy_name: str) -> WorkflowStrategy

Create a workflow strategy instance based on the strategy name.

Parameters:

Name	Type	Description	Default
strategy_name	str	The name of the workflow strategy to create.	required

Returns:

Type	Description
WorkflowStrategy	An instance of the requested workflow strategy.

Raises:

Type	Description
ValueError	If the strategy name is unknown.

Source code in src/codemap/git/pr_generator/strategies.py

def create_strategy(strategy_name: str) -> WorkflowStrategy:
	"""
	Create a workflow strategy instance based on the strategy name.

	Args:
	    strategy_name: The name of the workflow strategy to create.

	Returns:
	    An instance of the requested workflow strategy.

	Raises:
	    ValueError: If the strategy name is unknown.

	"""
	strategy_class = get_strategy_class(strategy_name)
	if not strategy_class:
		error_msg = f"Unknown workflow strategy: {strategy_name}"
		raise ValueError(error_msg)

	return strategy_class()

branch_exists

branch_exists(
	branch_name: str, include_remote: bool = True
) -> bool

Check if a branch exists.

Parameters:

Name	Type	Description	Default
branch_name	str	Name of the branch to check	required
include_remote	bool	Whether to check remote branches as well	True

Returns:

Type	Description
bool	True if the branch exists, False otherwise

Source code in src/codemap/git/pr_generator/strategies.py

def branch_exists(branch_name: str, include_remote: bool = True) -> bool:
	"""
	Check if a branch exists.

	Args:
	    branch_name: Name of the branch to check
	    include_remote: Whether to check remote branches as well

	Returns:
	    True if the branch exists, False otherwise

	"""
	if not branch_name:
		return False

	try:
		# First check local branches
		try:
			branches = run_git_command(["git", "branch", "--list", branch_name]).strip()
			if branches:
				return True
		except GitError:
			# If local check fails, don't fail immediately
			pass

		# Then check remote branches if requested
		if include_remote:
			try:
				remote_branches = run_git_command(["git", "branch", "-r", "--list", f"origin/{branch_name}"]).strip()
				if remote_branches:
					return True
			except GitError:
				# If remote check fails, don't fail immediately
				pass

		# If we get here, the branch doesn't exist or commands failed
		return False
	except GitError:
		return False

get_default_branch

get_default_branch() -> str

Get the default branch of the repository.

Returns:

Type	Description
str	Name of the default branch (usually main or master)

Source code in src/codemap/git/pr_generator/strategies.py

def get_default_branch() -> str:
	"""
	Get the default branch of the repository.

	Returns:
	    Name of the default branch (usually main or master)

	"""
	try:
		# Try to get the default branch from the remote
		remote_info = run_git_command(["git", "remote", "show", "origin"])
		match = re.search(r"HEAD branch: (\S+)", remote_info)
		if match:
			return match.group(1)

		# Fallback to checking if main or master exists
		branches = run_git_command(["git", "branch", "-r"]).splitlines()
		if any("origin/main" in branch for branch in branches):
			return "main"
		if any("origin/master" in branch for branch in branches):
			return "master"

		# Last resort, use current branch
		return run_git_command(["git", "branch", "--show-current"]).strip()
	except GitError:
		return "main"

command

Main PR generation command implementation for CodeMap.

logger module-attribute

logger = getLogger(__name__)

PRCommand

Handles the PR generation command workflow.

Source code in src/codemap/git/pr_generator/command.py

class PRCommand:
	"""Handles the PR generation command workflow."""

	def __init__(self, path: Path | None = None, model: str = "gpt-4o-mini") -> None:
		"""
		Initialize the PR command.

		Args:
		    path: Optional path to start from
		    model: LLM model to use for PR description generation

		"""
		try:
			self.repo_root = get_repo_root(path)

			# Create LLM client and configs
			from codemap.llm import create_client

			llm_client = create_client(repo_path=self.repo_root, model=model)

			# Create the PR generator with required parameters
			self.pr_generator = PRGenerator(
				repo_path=self.repo_root,
				llm_client=llm_client,
			)

			self.error_state = None  # Tracks reason for failure: "failed", "aborted", etc.
		except GitError as e:
			raise RuntimeError(str(e)) from e

	def _get_branch_info(self) -> dict[str, str]:
		"""
		Get information about the current branch and its target.

		Returns:
		    Dictionary with branch information

		Raises:
		    RuntimeError: If Git operations fail

		"""
		try:
			# Get current branch
			current_branch = run_git_command(["git", "rev-parse", "--abbrev-ref", "HEAD"]).strip()

			# Get default branch (usually main or master)
			default_branch = run_git_command(["git", "remote", "show", "origin"]).strip()
			# Parse the default branch from the output
			for line in default_branch.splitlines():
				if "HEAD branch" in line:
					default_branch = line.split(":")[-1].strip()
					break

			return {"current_branch": current_branch, "target_branch": default_branch}
		except GitError as e:
			msg = f"Failed to get branch information: {e}"
			raise RuntimeError(msg) from e

	def _get_commit_history(self, base_branch: str) -> list[dict[str, str]]:
		"""
		Get commit history between the current branch and the base branch.

		Args:
		    base_branch: The base branch to compare against

		Returns:
		    List of commits with their details

		Raises:
		    RuntimeError: If Git operations fail

		"""
		try:
			# Get list of commits that are in the current branch but not in the base branch
			commits_output = run_git_command(["git", "log", f"{base_branch}..HEAD", "--pretty=format:%H||%an||%s"])

			commits = []
			if commits_output.strip():
				for commit_line in commits_output.strip().split("\n"):
					if not commit_line.strip():
						continue

					parts = commit_line.split("||")
					if len(parts) >= MIN_COMMIT_PARTS:
						commit_hash, author, subject = parts[0], parts[1], parts[2]
						commits.append({"hash": commit_hash, "author": author, "subject": subject})

			return commits
		except GitError as e:
			msg = f"Failed to get commit history: {e}"
			raise RuntimeError(msg) from e

	def _generate_pr_description(self, branch_info: dict[str, str], _commits: list[dict[str, str]]) -> str:
		"""
		Generate PR description based on branch info and commit history.

		Args:
		    branch_info: Information about the branches
		    _commits: List of commits to include in the description (fetched internally by PRGenerator)

		Returns:
		    Generated PR description

		Raises:
		    RuntimeError: If description generation fails

		"""
		try:
			with loading_spinner("Generating PR description using LLM..."):
				# Use the PR generator to create content
				content = self.pr_generator.generate_content_from_commits(
					base_branch=branch_info["target_branch"], head_branch=branch_info["current_branch"], use_llm=True
				)
				return content["description"]
		except LLMError as e:
			logger.exception("LLM description generation failed")
			logger.warning("LLM error: %s", str(e))

			# Generate a simple fallback description without LLM
			with loading_spinner("Falling back to simple PR description generation..."):
				content = self.pr_generator.generate_content_from_commits(
					base_branch=branch_info["target_branch"], head_branch=branch_info["current_branch"], use_llm=False
				)
				return content["description"]
		except (ValueError, RuntimeError) as e:
			logger.warning("Error generating PR description: %s", str(e))
			msg = f"Failed to generate PR description: {e}"
			raise RuntimeError(msg) from e

	def _raise_no_commits_error(self, branch_info: dict[str, str]) -> None:
		"""
		Raise an error when no commits are found between branches.

		Args:
		    branch_info: Information about the branches

		Raises:
		    RuntimeError: Always raises this error with appropriate message

		"""
		msg = f"No commits found between {branch_info['current_branch']} and {branch_info['target_branch']}"
		logger.warning(msg)
		raise RuntimeError(msg)

	def run(self) -> dict[str, Any]:
		"""
		Run the PR generation command.

		Returns:
		    Dictionary with PR information and generated description

		Raises:
		    RuntimeError: If the command fails

		"""
		try:
			# Get branch information
			with loading_spinner("Getting branch information..."):
				branch_info = self._get_branch_info()

			# Get commit history
			with loading_spinner("Retrieving commit history..."):
				commits = self._get_commit_history(branch_info["target_branch"])

			if not commits:
				self._raise_no_commits_error(branch_info)

			# Generate PR description
			description = self._generate_pr_description(branch_info, commits)

			return {"branch_info": branch_info, "commits": commits, "description": description}
		except (RuntimeError, ValueError) as e:
			self.error_state = "failed"
			raise RuntimeError(str(e)) from e

__init__

__init__(
	path: Path | None = None, model: str = "gpt-4o-mini"
) -> None

Initialize the PR command.

Parameters:

Name	Type	Description	Default
path	Path | None	Optional path to start from	None
model	str	LLM model to use for PR description generation	'gpt-4o-mini'

Source code in src/codemap/git/pr_generator/command.py

def __init__(self, path: Path | None = None, model: str = "gpt-4o-mini") -> None:
	"""
	Initialize the PR command.

	Args:
	    path: Optional path to start from
	    model: LLM model to use for PR description generation

	"""
	try:
		self.repo_root = get_repo_root(path)

		# Create LLM client and configs
		from codemap.llm import create_client

		llm_client = create_client(repo_path=self.repo_root, model=model)

		# Create the PR generator with required parameters
		self.pr_generator = PRGenerator(
			repo_path=self.repo_root,
			llm_client=llm_client,
		)

		self.error_state = None  # Tracks reason for failure: "failed", "aborted", etc.
	except GitError as e:
		raise RuntimeError(str(e)) from e

repo_root instance-attribute

repo_root = get_repo_root(path)

pr_generator instance-attribute

pr_generator = PRGenerator(
	repo_path=repo_root, llm_client=llm_client
)

error_state instance-attribute

error_state = None

run

run() -> dict[str, Any]

Run the PR generation command.

Returns:

Type	Description
dict[str, Any]	Dictionary with PR information and generated description

Raises:

Type	Description
RuntimeError	If the command fails

Source code in src/codemap/git/pr_generator/command.py

def run(self) -> dict[str, Any]:
	"""
	Run the PR generation command.

	Returns:
	    Dictionary with PR information and generated description

	Raises:
	    RuntimeError: If the command fails

	"""
	try:
		# Get branch information
		with loading_spinner("Getting branch information..."):
			branch_info = self._get_branch_info()

		# Get commit history
		with loading_spinner("Retrieving commit history..."):
			commits = self._get_commit_history(branch_info["target_branch"])

		if not commits:
			self._raise_no_commits_error(branch_info)

		# Generate PR description
		description = self._generate_pr_description(branch_info, commits)

		return {"branch_info": branch_info, "commits": commits, "description": description}
	except (RuntimeError, ValueError) as e:
		self.error_state = "failed"
		raise RuntimeError(str(e)) from e

PRWorkflowCommand

Handles the core PR creation and update workflow logic.

Source code in src/codemap/git/pr_generator/command.py

class PRWorkflowCommand:
	"""Handles the core PR creation and update workflow logic."""

	def __init__(
		self,
		repo_path: Path,
		config_loader: ConfigLoader,
		llm_client: LLMClient | None = None,
		model: str | None = None,
		api_key: str | None = None,
		api_base: str | None = None,
	) -> None:
		"""
		Initialize the PR workflow command helper.

		Args:
		        repo_path: Path to the repository.
		        config_loader: ConfigLoader instance.
		        llm_client: Optional pre-configured LLMClient.
		        model: LLM model name (used if llm_client is None).
		        api_key: API key (used if llm_client is None).
		        api_base: API base URL (used if llm_client is None).

		"""
		self.repo_path = repo_path
		self.config_loader = config_loader
		self.pr_config = self.config_loader.config.get("pr", {})
		self.content_config = self.pr_config.get("content", {})
		self.workflow_strategy_name = self.config_loader.get_workflow_strategy()
		self.workflow = create_strategy(self.workflow_strategy_name)

		# Initialize LLM client if needed
		if llm_client:
			self.llm_client = llm_client
		else:
			from codemap.llm import create_client

			self.llm_client = create_client(
				repo_path=self.repo_path,
				model=model,
				api_key=api_key,
				api_base=api_base,
			)

		self.pr_generator = PRGenerator(repo_path=self.repo_path, llm_client=self.llm_client)

	def _generate_release_pr_content(self, base_branch: str, branch_name: str) -> dict[str, str]:
		"""
		Generate PR content for a release.

		Args:
		        base_branch: The branch to merge into (e.g. main)
		        branch_name: The release branch name (e.g. release/1.0.0)

		Returns:
		        Dictionary with title and description

		"""
		# Extract version from branch name
		version = branch_name.replace("release/", "")
		title = f"Release {version}"
		# Include base branch information in the description
		description = f"# Release {version}\n\nThis pull request merges release {version} into {base_branch}."
		return {"title": title, "description": description}

	def _generate_title(self, commits: list[str], branch_name: str, branch_type: str) -> str:
		"""Core logic for generating PR title."""
		title_strategy = self.content_config.get("title_strategy", "commits")

		if not commits:
			if branch_type == "release":
				return f"Release {branch_name.replace('release/', '')}"
			clean_name = branch_name.replace(f"{branch_type}/", "").replace("-", " ").replace("_", " ")
			return f"{branch_type.capitalize()}: {clean_name.capitalize()}"

		if title_strategy == "llm":
			return generate_pr_title_with_llm(commits, llm_client=self.llm_client)

		return generate_pr_title_from_commits(commits)

	def _generate_description(self, commits: list[str], branch_name: str, branch_type: str, base_branch: str) -> str:
		"""Core logic for generating PR description."""
		description_strategy = self.content_config.get("description_strategy", "commits")

		if not commits:
			if branch_type == "release" and self.workflow_strategy_name == "gitflow":
				# Call the internal helper method
				content = self._generate_release_pr_content(base_branch, branch_name)
				return content["description"]
			return f"Changes in {branch_name}"

		if description_strategy == "llm":
			return generate_pr_description_with_llm(commits, llm_client=self.llm_client)

		if description_strategy == "template" and not self.content_config.get("use_workflow_templates", True):
			template = self.content_config.get("description_template", "")
			if template:
				commit_description = "\n".join([f"- {commit}" for commit in commits])
				# Note: Other template variables like testing_instructions might need context
				return template.format(
					changes=commit_description,
					testing_instructions="[Testing instructions]",
					screenshots="[Screenshots]",
				)

		return generate_pr_description_from_commits(commits)

	def create_pr_workflow(
		self, base_branch: str, head_branch: str, title: str | None = None, description: str | None = None
	) -> PullRequest:
		"""Orchestrates the PR creation process (non-interactive part)."""
		try:
			# Check for existing PR first
			existing_pr = get_existing_pr(head_branch)
			if existing_pr:
				logger.warning(
					f"PR #{existing_pr.number} already exists for branch '{head_branch}'. Returning existing PR."
				)
				return existing_pr

			# Get commits
			commits = get_commit_messages(base_branch, head_branch)

			# Determine branch type
			branch_type = self.workflow.detect_branch_type(head_branch) or "feature"

			# Generate title and description if not provided
			final_title = title or self._generate_title(commits, head_branch, branch_type)
			final_description = description or self._generate_description(
				commits, head_branch, branch_type, base_branch
			)

			# Create PR using PRGenerator
			pr = self.pr_generator.create_pr(base_branch, head_branch, final_title, final_description)
			logger.info(f"Successfully created PR #{pr.number}: {pr.url}")
			return pr
		except GitError:
			# Specific handling for unrelated histories might go here or be handled in CLI
			logger.exception("GitError during PR creation workflow")
			raise
		except Exception as e:
			logger.exception("Unexpected error during PR creation workflow")
			msg = f"Unexpected error creating PR: {e}"
			raise PRCreationError(msg) from e

	def update_pr_workflow(
		self,
		pr_number: int,
		title: str | None = None,
		description: str | None = None,
		base_branch: str | None = None,
		head_branch: str | None = None,
	) -> PullRequest:
		"""Orchestrates the PR update process (non-interactive part)."""
		try:
			# Fetch existing PR info if needed to regenerate title/description
			# This might require gh cli or GitHub API interaction if pr_generator doesn't fetch
			# For now, assume base/head are provided if regeneration is needed

			final_title = title
			final_description = description

			# Regenerate if title/description are None
			if title is None or description is None:
				if not base_branch or not head_branch:
					msg = "Cannot regenerate content for update without base and head branches."
					raise PRCreationError(msg)

				commits = get_commit_messages(base_branch, head_branch)
				branch_type = self.workflow.detect_branch_type(head_branch) or "feature"

				if title is None:
					final_title = self._generate_title(commits, head_branch, branch_type)
				if description is None:
					final_description = self._generate_description(commits, head_branch, branch_type, base_branch)

			if final_title is None or final_description is None:
				msg = "Could not determine final title or description for PR update."
				raise PRCreationError(msg)

			# Update PR using PRGenerator
			updated_pr = self.pr_generator.update_pr(pr_number, final_title, final_description)
			logger.info(f"Successfully updated PR #{updated_pr.number}: {updated_pr.url}")
			return updated_pr
		except GitError:
			logger.exception("GitError during PR update workflow")
			raise
		except Exception as e:
			logger.exception("Unexpected error during PR update workflow")
			msg = f"Unexpected error updating PR: {e}"
			raise PRCreationError(msg) from e

			logger.exception("Unexpected error during PR update workflow")
			msg = f"Unexpected error updating PR: {e}"
			raise PRCreationError(msg) from e

__init__

__init__(
	repo_path: Path,
	config_loader: ConfigLoader,
	llm_client: LLMClient | None = None,
	model: str | None = None,
	api_key: str | None = None,
	api_base: str | None = None,
) -> None

Initialize the PR workflow command helper.

Parameters:

Name	Type	Description	Default
repo_path	Path	Path to the repository.	required
config_loader	ConfigLoader	ConfigLoader instance.	required
llm_client	LLMClient | None	Optional pre-configured LLMClient.	None
model	str | None	LLM model name (used if llm_client is None).	None
api_key	str | None	API key (used if llm_client is None).	None
api_base	str | None	API base URL (used if llm_client is None).	None

Source code in src/codemap/git/pr_generator/command.py

def __init__(
	self,
	repo_path: Path,
	config_loader: ConfigLoader,
	llm_client: LLMClient | None = None,
	model: str | None = None,
	api_key: str | None = None,
	api_base: str | None = None,
) -> None:
	"""
	Initialize the PR workflow command helper.

	Args:
	        repo_path: Path to the repository.
	        config_loader: ConfigLoader instance.
	        llm_client: Optional pre-configured LLMClient.
	        model: LLM model name (used if llm_client is None).
	        api_key: API key (used if llm_client is None).
	        api_base: API base URL (used if llm_client is None).

	"""
	self.repo_path = repo_path
	self.config_loader = config_loader
	self.pr_config = self.config_loader.config.get("pr", {})
	self.content_config = self.pr_config.get("content", {})
	self.workflow_strategy_name = self.config_loader.get_workflow_strategy()
	self.workflow = create_strategy(self.workflow_strategy_name)

	# Initialize LLM client if needed
	if llm_client:
		self.llm_client = llm_client
	else:
		from codemap.llm import create_client

		self.llm_client = create_client(
			repo_path=self.repo_path,
			model=model,
			api_key=api_key,
			api_base=api_base,
		)

	self.pr_generator = PRGenerator(repo_path=self.repo_path, llm_client=self.llm_client)

repo_path instance-attribute

repo_path = repo_path

config_loader instance-attribute

config_loader = config_loader

pr_config instance-attribute

pr_config = get('pr', {})

content_config instance-attribute

content_config = get('content', {})

workflow_strategy_name instance-attribute

workflow_strategy_name = get_workflow_strategy()

workflow instance-attribute

workflow = create_strategy(workflow_strategy_name)

llm_client instance-attribute

llm_client = llm_client

pr_generator instance-attribute

pr_generator = PRGenerator(
	repo_path=repo_path, llm_client=llm_client
)

create_pr_workflow

create_pr_workflow(
	base_branch: str,
	head_branch: str,
	title: str | None = None,
	description: str | None = None,
) -> PullRequest

Orchestrates the PR creation process (non-interactive part).

Source code in src/codemap/git/pr_generator/command.py

def create_pr_workflow(
	self, base_branch: str, head_branch: str, title: str | None = None, description: str | None = None
) -> PullRequest:
	"""Orchestrates the PR creation process (non-interactive part)."""
	try:
		# Check for existing PR first
		existing_pr = get_existing_pr(head_branch)
		if existing_pr:
			logger.warning(
				f"PR #{existing_pr.number} already exists for branch '{head_branch}'. Returning existing PR."
			)
			return existing_pr

		# Get commits
		commits = get_commit_messages(base_branch, head_branch)

		# Determine branch type
		branch_type = self.workflow.detect_branch_type(head_branch) or "feature"

		# Generate title and description if not provided
		final_title = title or self._generate_title(commits, head_branch, branch_type)
		final_description = description or self._generate_description(
			commits, head_branch, branch_type, base_branch
		)

		# Create PR using PRGenerator
		pr = self.pr_generator.create_pr(base_branch, head_branch, final_title, final_description)
		logger.info(f"Successfully created PR #{pr.number}: {pr.url}")
		return pr
	except GitError:
		# Specific handling for unrelated histories might go here or be handled in CLI
		logger.exception("GitError during PR creation workflow")
		raise
	except Exception as e:
		logger.exception("Unexpected error during PR creation workflow")
		msg = f"Unexpected error creating PR: {e}"
		raise PRCreationError(msg) from e

update_pr_workflow

update_pr_workflow(
	pr_number: int,
	title: str | None = None,
	description: str | None = None,
	base_branch: str | None = None,
	head_branch: str | None = None,
) -> PullRequest

Orchestrates the PR update process (non-interactive part).

Source code in src/codemap/git/pr_generator/command.py

def update_pr_workflow(
	self,
	pr_number: int,
	title: str | None = None,
	description: str | None = None,
	base_branch: str | None = None,
	head_branch: str | None = None,
) -> PullRequest:
	"""Orchestrates the PR update process (non-interactive part)."""
	try:
		# Fetch existing PR info if needed to regenerate title/description
		# This might require gh cli or GitHub API interaction if pr_generator doesn't fetch
		# For now, assume base/head are provided if regeneration is needed

		final_title = title
		final_description = description

		# Regenerate if title/description are None
		if title is None or description is None:
			if not base_branch or not head_branch:
				msg = "Cannot regenerate content for update without base and head branches."
				raise PRCreationError(msg)

			commits = get_commit_messages(base_branch, head_branch)
			branch_type = self.workflow.detect_branch_type(head_branch) or "feature"

			if title is None:
				final_title = self._generate_title(commits, head_branch, branch_type)
			if description is None:
				final_description = self._generate_description(commits, head_branch, branch_type, base_branch)

		if final_title is None or final_description is None:
			msg = "Could not determine final title or description for PR update."
			raise PRCreationError(msg)

		# Update PR using PRGenerator
		updated_pr = self.pr_generator.update_pr(pr_number, final_title, final_description)
		logger.info(f"Successfully updated PR #{updated_pr.number}: {updated_pr.url}")
		return updated_pr
	except GitError:
		logger.exception("GitError during PR update workflow")
		raise
	except Exception as e:
		logger.exception("Unexpected error during PR update workflow")
		msg = f"Unexpected error updating PR: {e}"
		raise PRCreationError(msg) from e

		logger.exception("Unexpected error during PR update workflow")
		msg = f"Unexpected error updating PR: {e}"
		raise PRCreationError(msg) from e

generator

PR generator for the CodeMap Git module.

This class generates pull requests for git repositories.

logger module-attribute

logger = getLogger(__name__)

PRGenerator

Generator for Pull Requests.

This class handles generating pull request content (title and description) and creating/updating PRs on GitHub.

Source code in src/codemap/git/pr_generator/generator.py

class PRGenerator:
	"""
	Generator for Pull Requests.

	This class handles generating pull request content (title and
	description) and creating/updating PRs on GitHub.

	"""

	def __init__(
		self,
		repo_path: Path,
		llm_client: LLMClient,
	) -> None:
		"""
		Initialize the PR generator.

		Args:
		    repo_path: Path to the git repository
		    llm_client: LLMClient instance to use for content generation

		"""
		self.repo_path = repo_path
		self.client = llm_client

	def generate_content_from_commits(self, base_branch: str, head_branch: str, use_llm: bool = True) -> PRContent:
		"""
		Generate PR content (title and description) from commits.

		Args:
		    base_branch: Base branch (e.g., main)
		    head_branch: Head branch (e.g., feature-branch)
		    use_llm: Whether to use LLM for generation

		Returns:
		    Dictionary with 'title' and 'description' keys

		"""
		# Get commit messages between branches
		commits = get_commit_messages(base_branch, head_branch)

		if not commits:
			return {"title": "Update branch", "description": "No changes in this PR."}

		if use_llm:
			# Generate title and description using LLM
			title = generate_pr_title_with_llm(commits, self.client)
			description = generate_pr_description_with_llm(commits, self.client)
		else:
			# Generate title and description using rule-based approach
			title = generate_pr_title_from_commits(commits)
			description = generate_pr_description_from_commits(commits)

		return {"title": title, "description": description}

	def generate_content_from_template(
		self, branch_name: str, description: str, workflow_strategy: str = "github-flow"
	) -> PRContent:
		"""
		Generate PR content (title and description) from a template.

		Args:
		    branch_name: Name of the branch
		    description: Short description of the changes
		    workflow_strategy: Git workflow strategy to use

		Returns:
		    Dictionary with 'title' and 'description' keys

		"""
		return generate_pr_content_from_template(branch_name, description, workflow_strategy)

	def suggest_branch_name(self, description: str, workflow_strategy: str = "github-flow") -> str:
		"""
		Suggest a branch name based on a description.

		Args:
		    description: Description of the branch
		    workflow_strategy: Git workflow strategy to use

		Returns:
		    Suggested branch name

		"""
		return suggest_branch_name(description, workflow_strategy)

	def create_pr(self, base_branch: str, head_branch: str, title: str, description: str) -> PullRequest:
		"""
		Create a pull request on GitHub.

		Args:
		    base_branch: Base branch (e.g., main)
		    head_branch: Head branch (e.g., feature-branch)
		    title: PR title
		    description: PR description

		Returns:
		    PullRequest object with PR details

		Raises:
		    GitError: If PR creation fails

		"""
		return create_pull_request(base_branch, head_branch, title, description)

	def update_pr(self, pr_number: int, title: str, description: str) -> PullRequest:
		"""
		Update an existing pull request.

		Args:
		    pr_number: PR number
		    title: New PR title
		    description: New PR description

		Returns:
		    Updated PullRequest object

		Raises:
		    GitError: If PR update fails

		"""
		return update_pull_request(pr_number, title, description)

	def get_existing_pr(self, branch_name: str) -> PullRequest | None:
		"""
		Get an existing PR for a branch.

		Args:
		    branch_name: Branch name

		Returns:
		    PullRequest object if found, None otherwise

		"""
		return get_existing_pr(branch_name)

	def create_or_update_pr(
		self,
		base_branch: str | None = None,
		head_branch: str | None = None,
		title: str | None = None,
		description: str | None = None,
		use_llm: bool = True,
		pr_number: int | None = None,
	) -> PullRequest:
		"""
		Create a new PR or update an existing one.

		Args:
		    base_branch: Base branch (defaults to default branch)
		    head_branch: Head branch
		    title: PR title (if None, will be generated)
		    description: PR description (if None, will be generated)
		    use_llm: Whether to use LLM for content generation
		    pr_number: PR number for update (if None, will create new PR)

		Returns:
		    PullRequest object

		Raises:
		    GitError: If PR creation/update fails

		"""
		# Get default branch if base_branch is not specified
		if base_branch is None:
			base_branch = get_default_branch()

		# Set default head_branch to current branch if not specified
		if head_branch is None:
			try:
				from codemap.git.pr_generator.utils import get_current_branch

				head_branch = get_current_branch()
			except GitError as err:
				msg = "Failed to determine current branch"
				raise GitError(msg) from err

		# Check if PR exists
		existing_pr = None
		if pr_number is not None:
			# Updating an existing PR by number
			if title is None or description is None:
				# Need to fetch the PR to get current title/description
				existing_pr = self.get_existing_pr(head_branch)
				if existing_pr is None:
					msg = f"No PR found for branch {head_branch} with number {pr_number}"
					raise GitError(msg)

		else:
			# Look for existing PR for this branch
			existing_pr = self.get_existing_pr(head_branch)
			if existing_pr is not None:
				pr_number = existing_pr.number

		# Generate content if not provided
		if title is None or description is None:
			content = self.generate_content_from_commits(base_branch, head_branch, use_llm)
			if title is None:
				title = content["title"]
			if description is None:
				description = content["description"]

		# Create or update PR
		if pr_number is not None:
			# Update existing PR
			return self.update_pr(pr_number, title, description)
		# Create new PR
		return self.create_pr(base_branch, head_branch, title, description)

__init__

__init__(repo_path: Path, llm_client: LLMClient) -> None

Initialize the PR generator.

Parameters:

Name	Type	Description	Default
repo_path	Path	Path to the git repository	required
llm_client	LLMClient	LLMClient instance to use for content generation	required

Source code in src/codemap/git/pr_generator/generator.py

def __init__(
	self,
	repo_path: Path,
	llm_client: LLMClient,
) -> None:
	"""
	Initialize the PR generator.

	Args:
	    repo_path: Path to the git repository
	    llm_client: LLMClient instance to use for content generation

	"""
	self.repo_path = repo_path
	self.client = llm_client

repo_path instance-attribute

repo_path = repo_path

client instance-attribute

client = llm_client

generate_content_from_commits

generate_content_from_commits(
	base_branch: str, head_branch: str, use_llm: bool = True
) -> PRContent

Generate PR content (title and description) from commits.

Parameters:

Name	Type	Description	Default
base_branch	str	Base branch (e.g., main)	required
head_branch	str	Head branch (e.g., feature-branch)	required
use_llm	bool	Whether to use LLM for generation	True

Returns:

Type	Description
PRContent	Dictionary with 'title' and 'description' keys

Source code in src/codemap/git/pr_generator/generator.py

def generate_content_from_commits(self, base_branch: str, head_branch: str, use_llm: bool = True) -> PRContent:
	"""
	Generate PR content (title and description) from commits.

	Args:
	    base_branch: Base branch (e.g., main)
	    head_branch: Head branch (e.g., feature-branch)
	    use_llm: Whether to use LLM for generation

	Returns:
	    Dictionary with 'title' and 'description' keys

	"""
	# Get commit messages between branches
	commits = get_commit_messages(base_branch, head_branch)

	if not commits:
		return {"title": "Update branch", "description": "No changes in this PR."}

	if use_llm:
		# Generate title and description using LLM
		title = generate_pr_title_with_llm(commits, self.client)
		description = generate_pr_description_with_llm(commits, self.client)
	else:
		# Generate title and description using rule-based approach
		title = generate_pr_title_from_commits(commits)
		description = generate_pr_description_from_commits(commits)

	return {"title": title, "description": description}

generate_content_from_template

generate_content_from_template(
	branch_name: str,
	description: str,
	workflow_strategy: str = "github-flow",
) -> PRContent

Generate PR content (title and description) from a template.

Parameters:

Name	Type	Description	Default
branch_name	str	Name of the branch	required
description	str	Short description of the changes	required
workflow_strategy	str	Git workflow strategy to use	'github-flow'

Returns:

Type	Description
PRContent	Dictionary with 'title' and 'description' keys

Source code in src/codemap/git/pr_generator/generator.py

def generate_content_from_template(
	self, branch_name: str, description: str, workflow_strategy: str = "github-flow"
) -> PRContent:
	"""
	Generate PR content (title and description) from a template.

	Args:
	    branch_name: Name of the branch
	    description: Short description of the changes
	    workflow_strategy: Git workflow strategy to use

	Returns:
	    Dictionary with 'title' and 'description' keys

	"""
	return generate_pr_content_from_template(branch_name, description, workflow_strategy)

suggest_branch_name

suggest_branch_name(
	description: str, workflow_strategy: str = "github-flow"
) -> str

Suggest a branch name based on a description.

Parameters:

Name	Type	Description	Default
description	str	Description of the branch	required
workflow_strategy	str	Git workflow strategy to use	'github-flow'

Returns:

Type	Description
str	Suggested branch name

Source code in src/codemap/git/pr_generator/generator.py

def suggest_branch_name(self, description: str, workflow_strategy: str = "github-flow") -> str:
	"""
	Suggest a branch name based on a description.

	Args:
	    description: Description of the branch
	    workflow_strategy: Git workflow strategy to use

	Returns:
	    Suggested branch name

	"""
	return suggest_branch_name(description, workflow_strategy)

create_pr

create_pr(
	base_branch: str,
	head_branch: str,
	title: str,
	description: str,
) -> PullRequest

Create a pull request on GitHub.

Parameters:

Name	Type	Description	Default
base_branch	str	Base branch (e.g., main)	required
head_branch	str	Head branch (e.g., feature-branch)	required
title	str	PR title	required
description	str	PR description	required

Returns:

Type	Description
PullRequest	PullRequest object with PR details

Raises:

Type	Description
GitError	If PR creation fails

Source code in src/codemap/git/pr_generator/generator.py

def create_pr(self, base_branch: str, head_branch: str, title: str, description: str) -> PullRequest:
	"""
	Create a pull request on GitHub.

	Args:
	    base_branch: Base branch (e.g., main)
	    head_branch: Head branch (e.g., feature-branch)
	    title: PR title
	    description: PR description

	Returns:
	    PullRequest object with PR details

	Raises:
	    GitError: If PR creation fails

	"""
	return create_pull_request(base_branch, head_branch, title, description)

update_pr

update_pr(
	pr_number: int, title: str, description: str
) -> PullRequest

Update an existing pull request.

Parameters:

Name	Type	Description	Default
pr_number	int	PR number	required
title	str	New PR title	required
description	str	New PR description	required

Returns:

Type	Description
PullRequest	Updated PullRequest object

Raises:

Type	Description
GitError	If PR update fails

Source code in src/codemap/git/pr_generator/generator.py

def update_pr(self, pr_number: int, title: str, description: str) -> PullRequest:
	"""
	Update an existing pull request.

	Args:
	    pr_number: PR number
	    title: New PR title
	    description: New PR description

	Returns:
	    Updated PullRequest object

	Raises:
	    GitError: If PR update fails

	"""
	return update_pull_request(pr_number, title, description)

get_existing_pr

get_existing_pr(branch_name: str) -> PullRequest | None

Get an existing PR for a branch.

Parameters:

Name	Type	Description	Default
branch_name	str	Branch name	required

Returns:

Type	Description
PullRequest | None	PullRequest object if found, None otherwise

Source code in src/codemap/git/pr_generator/generator.py

def get_existing_pr(self, branch_name: str) -> PullRequest | None:
	"""
	Get an existing PR for a branch.

	Args:
	    branch_name: Branch name

	Returns:
	    PullRequest object if found, None otherwise

	"""
	return get_existing_pr(branch_name)

create_or_update_pr

create_or_update_pr(
	base_branch: str | None = None,
	head_branch: str | None = None,
	title: str | None = None,
	description: str | None = None,
	use_llm: bool = True,
	pr_number: int | None = None,
) -> PullRequest

Create a new PR or update an existing one.

Parameters:

Name	Type	Description	Default
base_branch	str | None	Base branch (defaults to default branch)	None
head_branch	str | None	Head branch	None
title	str | None	PR title (if None, will be generated)	None
description	str | None	PR description (if None, will be generated)	None
use_llm	bool	Whether to use LLM for content generation	True
pr_number	int | None	PR number for update (if None, will create new PR)	None

Returns:

Type	Description
PullRequest	PullRequest object

Raises:

Type	Description
GitError	If PR creation/update fails

Source code in src/codemap/git/pr_generator/generator.py

def create_or_update_pr(
	self,
	base_branch: str | None = None,
	head_branch: str | None = None,
	title: str | None = None,
	description: str | None = None,
	use_llm: bool = True,
	pr_number: int | None = None,
) -> PullRequest:
	"""
	Create a new PR or update an existing one.

	Args:
	    base_branch: Base branch (defaults to default branch)
	    head_branch: Head branch
	    title: PR title (if None, will be generated)
	    description: PR description (if None, will be generated)
	    use_llm: Whether to use LLM for content generation
	    pr_number: PR number for update (if None, will create new PR)

	Returns:
	    PullRequest object

	Raises:
	    GitError: If PR creation/update fails

	"""
	# Get default branch if base_branch is not specified
	if base_branch is None:
		base_branch = get_default_branch()

	# Set default head_branch to current branch if not specified
	if head_branch is None:
		try:
			from codemap.git.pr_generator.utils import get_current_branch

			head_branch = get_current_branch()
		except GitError as err:
			msg = "Failed to determine current branch"
			raise GitError(msg) from err

	# Check if PR exists
	existing_pr = None
	if pr_number is not None:
		# Updating an existing PR by number
		if title is None or description is None:
			# Need to fetch the PR to get current title/description
			existing_pr = self.get_existing_pr(head_branch)
			if existing_pr is None:
				msg = f"No PR found for branch {head_branch} with number {pr_number}"
				raise GitError(msg)

	else:
		# Look for existing PR for this branch
		existing_pr = self.get_existing_pr(head_branch)
		if existing_pr is not None:
			pr_number = existing_pr.number

	# Generate content if not provided
	if title is None or description is None:
		content = self.generate_content_from_commits(base_branch, head_branch, use_llm)
		if title is None:
			title = content["title"]
		if description is None:
			description = content["description"]

	# Create or update PR
	if pr_number is not None:
		# Update existing PR
		return self.update_pr(pr_number, title, description)
	# Create new PR
	return self.create_pr(base_branch, head_branch, title, description)

diff_splitter

Diff splitting package for CodeMap.

This package provides utilities for splitting Git diffs into logical chunks.

MIN_NAME_LENGTH_FOR_SIMILARITY module-attribute

MIN_NAME_LENGTH_FOR_SIMILARITY: Final = 3

DiffChunk dataclass

Represents a logical chunk of changes.

Source code in src/codemap/git/diff_splitter/schemas.py

@dataclass
class DiffChunk:
	"""Represents a logical chunk of changes."""

	files: list[str]
	content: str
	description: str | None = None
	is_llm_generated: bool = False
	filtered_files: list[str] | None = None

	def __post_init__(self) -> None:
		"""Initialize default values."""
		if self.filtered_files is None:
			self.filtered_files = []

	def __hash__(self) -> int:
		"""
		Make DiffChunk hashable by using the object's id.

		Returns:
		        Hash value based on the object's id

		"""
		return hash(id(self))

	def __eq__(self, other: object) -> bool:
		"""
		Compare DiffChunk objects for equality.

		Args:
		        other: Another object to compare with

		Returns:
		        True if the objects are the same instance, False otherwise

		"""
		if not isinstance(other, DiffChunk):
			return False
		return id(self) == id(other)

files instance-attribute

files: list[str]

content instance-attribute

content: str

description class-attribute instance-attribute

description: str | None = None

is_llm_generated class-attribute instance-attribute

is_llm_generated: bool = False

filtered_files class-attribute instance-attribute

filtered_files: list[str] | None = None

__post_init__

__post_init__() -> None

Initialize default values.

Source code in src/codemap/git/diff_splitter/schemas.py

def __post_init__(self) -> None:
	"""Initialize default values."""
	if self.filtered_files is None:
		self.filtered_files = []

__hash__

__hash__() -> int

Make DiffChunk hashable by using the object's id.

Returns:

Type	Description
int	Hash value based on the object's id

Source code in src/codemap/git/diff_splitter/schemas.py

def __hash__(self) -> int:
	"""
	Make DiffChunk hashable by using the object's id.

	Returns:
	        Hash value based on the object's id

	"""
	return hash(id(self))

__eq__

__eq__(other: object) -> bool

Compare DiffChunk objects for equality.

Parameters:

Name	Type	Description	Default
other	object	Another object to compare with	required

Returns:

Type	Description
bool	True if the objects are the same instance, False otherwise

Source code in src/codemap/git/diff_splitter/schemas.py

def __eq__(self, other: object) -> bool:
	"""
	Compare DiffChunk objects for equality.

	Args:
	        other: Another object to compare with

	Returns:
	        True if the objects are the same instance, False otherwise

	"""
	if not isinstance(other, DiffChunk):
		return False
	return id(self) == id(other)

__init__

__init__(
	files: list[str],
	content: str,
	description: str | None = None,
	is_llm_generated: bool = False,
	filtered_files: list[str] | None = None,
) -> None

DiffChunkData dataclass

Dictionary-based representation of a DiffChunk for serialization.

Source code in src/codemap/git/diff_splitter/schemas.py

@dataclass
class DiffChunkData:
	"""Dictionary-based representation of a DiffChunk for serialization."""

	files: list[str]
	content: str
	description: str | None = None
	is_llm_generated: bool = False
	filtered_files: list[str] | None = None

	@classmethod
	def from_chunk(cls, chunk: DiffChunk) -> "DiffChunkData":
		"""Create a DiffChunkData from a DiffChunk."""
		return cls(
			files=chunk.files,
			content=chunk.content,
			description=chunk.description,
			is_llm_generated=chunk.is_llm_generated,
			filtered_files=chunk.filtered_files,
		)

	def to_chunk(self) -> DiffChunk:
		"""Convert DiffChunkData to a DiffChunk."""
		return DiffChunk(
			files=self.files,
			content=self.content,
			description=self.description,
			is_llm_generated=self.is_llm_generated,
			filtered_files=self.filtered_files,
		)

	def to_dict(self) -> dict[str, Any]:
		"""Convert to a dictionary."""
		return {
			"files": self.files,
			"content": self.content,
			"description": self.description,
			"is_llm_generated": self.is_llm_generated,
			"filtered_files": self.filtered_files,
		}

files instance-attribute

files: list[str]

content instance-attribute

content: str

description class-attribute instance-attribute

description: str | None = None

is_llm_generated class-attribute instance-attribute

is_llm_generated: bool = False

filtered_files class-attribute instance-attribute

filtered_files: list[str] | None = None

from_chunk classmethod

from_chunk(chunk: DiffChunk) -> DiffChunkData

Create a DiffChunkData from a DiffChunk.

Source code in src/codemap/git/diff_splitter/schemas.py

@classmethod
def from_chunk(cls, chunk: DiffChunk) -> "DiffChunkData":
	"""Create a DiffChunkData from a DiffChunk."""
	return cls(
		files=chunk.files,
		content=chunk.content,
		description=chunk.description,
		is_llm_generated=chunk.is_llm_generated,
		filtered_files=chunk.filtered_files,
	)

to_chunk

to_chunk() -> DiffChunk

Convert DiffChunkData to a DiffChunk.

Source code in src/codemap/git/diff_splitter/schemas.py

def to_chunk(self) -> DiffChunk:
	"""Convert DiffChunkData to a DiffChunk."""
	return DiffChunk(
		files=self.files,
		content=self.content,
		description=self.description,
		is_llm_generated=self.is_llm_generated,
		filtered_files=self.filtered_files,
	)

to_dict

to_dict() -> dict[str, Any]

Convert to a dictionary.

Source code in src/codemap/git/diff_splitter/schemas.py

def to_dict(self) -> dict[str, Any]:
	"""Convert to a dictionary."""
	return {
		"files": self.files,
		"content": self.content,
		"description": self.description,
		"is_llm_generated": self.is_llm_generated,
		"filtered_files": self.filtered_files,
	}

__init__

__init__(
	files: list[str],
	content: str,
	description: str | None = None,
	is_llm_generated: bool = False,
	filtered_files: list[str] | None = None,
) -> None

DiffSplitter

Splits Git diffs into logical chunks.

Source code in src/codemap/git/diff_splitter/splitter.py

class DiffSplitter:
	"""Splits Git diffs into logical chunks."""

	# Class-level cache for the embedding model
	_embedding_model = None
	# Track availability of sentence-transformers and the model
	_sentence_transformers_available = None
	_model_available = None

	def __init__(
		self,
		repo_root: Path,
		# Defaults are now sourced from DEFAULT_CONFIG
		similarity_threshold: float = DEFAULT_CONFIG["commit"]["diff_splitter"]["similarity_threshold"],
		directory_similarity_threshold: float = DEFAULT_CONFIG["commit"]["diff_splitter"][
			"directory_similarity_threshold"
		],
		min_chunks_for_consolidation: int = DEFAULT_CONFIG["commit"]["diff_splitter"]["min_chunks_for_consolidation"],
		max_chunks_before_consolidation: int = DEFAULT_CONFIG["commit"]["diff_splitter"][
			"max_chunks_before_consolidation"
		],
		max_file_size_for_llm: int = DEFAULT_CONFIG["commit"]["diff_splitter"]["max_file_size_for_llm"],
		max_log_diff_size: int = DEFAULT_CONFIG["commit"]["diff_splitter"]["max_log_diff_size"],
		model_name: str = DEFAULT_CONFIG["commit"]["diff_splitter"]["model_name"],
	) -> None:
		"""
		Initialize the diff splitter.

		Args:
		    repo_root: Root directory of the Git repository
		    similarity_threshold: Threshold for grouping by content similarity.
		    directory_similarity_threshold: Threshold for directory similarity.
		    min_chunks_for_consolidation: Min chunks to trigger consolidation.
		    max_chunks_before_consolidation: Max chunks allowed before forced consolidation.
		    max_file_size_for_llm: Max file size (bytes) to process for LLM context.
		        Defaults to value from `DEFAULT_CONFIG["commit"]["diff_splitter"]["max_file_size_for_llm"]` if None.
		    max_log_diff_size: Max diff size (bytes) to log in debug mode.
		        Defaults to value from `DEFAULT_CONFIG["commit"]["diff_splitter"]["max_log_diff_size"]` if None.
		    model_name: Name of the sentence-transformer model to use.
		        Defaults to value from `DEFAULT_CONFIG["commit"]["diff_splitter"]["model_name"]` if None.

		"""
		self.repo_root = repo_root
		# Store thresholds
		self.similarity_threshold = similarity_threshold
		self.directory_similarity_threshold = directory_similarity_threshold
		self.min_chunks_for_consolidation = min_chunks_for_consolidation
		self.max_chunks_before_consolidation = max_chunks_before_consolidation
		# Store other settings
		self.max_file_size_for_llm = max_file_size_for_llm
		self.max_log_diff_size = max_log_diff_size
		self.model_name = model_name

		# Do NOT automatically check availability - let the command class do this explicitly
		# This avoids checks happening during initialization without visible loading states

	@classmethod
	def _check_sentence_transformers_availability(cls) -> bool:
		"""
		Check if sentence-transformers package is available.

		Returns:
		    True if sentence-transformers is available, False otherwise

		"""
		try:
			# This is needed for the import check, but don't flag as unused
			import sentence_transformers  # type: ignore  # noqa: F401, PGH003

			# Set the class flag for future reference
			cls._sentence_transformers_available = True
			logger.debug("sentence-transformers is available")
			return True
		except ImportError as e:
			# Log the specific import error for better debugging
			cls._sentence_transformers_available = False
			logger.warning(
				"sentence-transformers import failed: %s. Semantic similarity features will be limited. "
				"Install with: pip install sentence-transformers numpy",
				e,
			)
			return False
		except (RuntimeError, ValueError, AttributeError) as e:
			# Catch specific errors during import
			cls._sentence_transformers_available = False
			logger.warning(
				"Unexpected error importing sentence-transformers: %s. Semantic similarity features will be limited.", e
			)
			return False

	@classmethod
	def are_sentence_transformers_available(cls) -> bool:
		"""
		Check if sentence transformers are available.

		Returns:
		    True if sentence transformers are available, False otherwise

		"""
		return cls._sentence_transformers_available or cls._check_sentence_transformers_availability()

	@classmethod
	def is_model_available(cls) -> bool:
		"""
		Check if embedding model is available.

		Returns:
		    True if embedding model is available, False otherwise

		"""
		return bool(cls._model_available)

	@classmethod
	def set_model_available(cls, value: bool) -> None:
		"""
		Set model availability flag.

		Args:
		    value: Boolean indicating if model is available

		"""
		cls._model_available = value

	@classmethod
	def get_embedding_model(cls) -> EmbeddingModel | None:
		"""
		Get the embedding model.

		Returns:
		    The embedding model or None if not available

		"""
		return cls._embedding_model

	@classmethod
	def set_embedding_model(cls, model: EmbeddingModel) -> None:
		"""
		Set the embedding model.

		Args:
		    model: The embedding model to set

		"""
		cls._embedding_model = model

	def _check_model_availability(self) -> bool:
		"""
		Check if the embedding model is available using the instance's configured model name.

		Returns:
		    True if model is available, False otherwise

		"""
		# Use class method to access class-level cache check
		if not self.__class__.are_sentence_transformers_available():
			return False

		try:
			from sentence_transformers import SentenceTransformer

			# Use class method to access class-level cache
			if self.__class__.get_embedding_model() is None:
				# Use self.model_name from instance configuration
				logger.debug("Loading embedding model: %s", self.model_name)

				try:
					console.print("Loading embedding model...")
					# Load the model using self.model_name
					model = SentenceTransformer(self.model_name)
					self.__class__.set_embedding_model(cast("EmbeddingModel", model))
					console.print("[green]✓[/green] Model loaded successfully")
					logger.debug("Initialized embedding model: %s", self.model_name)
					# Set class-level flag via class method
					self.__class__.set_model_available(True)
					return True
				except ImportError as e:
					logger.exception("Missing dependencies for embedding model")
					console.print(f"[red]Error: Missing dependencies: {e}[/red]")
					self.__class__.set_model_available(False)
					return False
				except MemoryError:
					logger.exception("Not enough memory to load embedding model")
					console.print("[red]Error: Not enough memory to load embedding model[/red]")
					self.__class__.set_model_available(False)
					return False
				except ValueError as e:
					logger.exception("Invalid model configuration")
					console.print(f"[red]Error: Invalid model configuration: {e}[/red]")
					self.__class__.set_model_available(False)
					return False
				except RuntimeError as e:
					error_msg = str(e)
					# Check for CUDA/GPU related errors
					if "CUDA" in error_msg or "GPU" in error_msg:
						logger.exception("GPU error when loading model")
						console.print("[red]Error: GPU/CUDA error. Try using CPU only mode.[/red]")
					else:
						logger.exception("Runtime error when loading model")
						console.print(f"[red]Error loading model: {error_msg}[/red]")
					self.__class__.set_model_available(False)
					return False
				except Exception as e:
					logger.exception("Unexpected error loading embedding model")
					console.print(f"[red]Unexpected error loading model: {e}[/red]")
					self.__class__.set_model_available(False)
					return False
			# If we already have a model loaded, make sure to set the flag to True
			self.__class__.set_model_available(True)
			return True
		except Exception as e:
			# This is the outer exception handler for any unexpected errors
			logger.exception("Failed to load embedding model %s", self.model_name)
			console.print(f"[red]Failed to load embedding model: {e}[/red]")
			self.__class__.set_model_available(False)
			return False

	def split_diff(self, diff: GitDiff) -> tuple[list[DiffChunk], list[str]]:
		"""
		Split a diff into logical chunks using semantic splitting.

		Args:
		    diff: GitDiff object to split

		Returns:
		    Tuple of (List of DiffChunk objects based on semantic analysis, List of filtered large files)

		Raises:
		    ValueError: If semantic splitting is not available or fails

		"""
		if not diff.files:
			return [], []

		# Special handling for untracked files - bypass semantic split since the content isn't a proper diff format
		if diff.is_untracked:
			logger.debug("Processing untracked files with special handling: %d files", len(diff.files))
			# Create a simple chunk per file to avoid errors with unidiff parsing
			chunks = []
			for file_path in diff.files:
				# Create a basic chunk with file info but without trying to parse the content as a diff
				chunks = [
					DiffChunk(
						files=[file_path],
						content=f"New untracked file: {file_path}",
						description=f"New file: {file_path}",
					)
					for file_path in diff.files
				]
			return chunks, []

		# In test environments, log the diff content for debugging
		if is_test_environment():
			logger.debug("Processing diff in test environment with %d files", len(diff.files) if diff.files else 0)
			if diff.content and len(diff.content) < self.max_log_diff_size:  # Use configured max log size
				logger.debug("Diff content: %s", diff.content)

		# Process files in the diff
		if diff.files:
			# Filter for valid files (existence, tracked status), max_size check removed here
			diff.files, _ = filter_valid_files(diff.files, is_test_environment())
			# filtered_large_files list is no longer populated or used here

		if not diff.files:
			logger.warning("No valid files to process after filtering")
			return [], []  # Return empty lists

		# Set up availability flags if not already set
		# Use class method to check sentence transformers availability
		if not self.__class__.are_sentence_transformers_available():
			msg = (
				"Semantic splitting is not available. sentence-transformers package is required. "
				"Install with: pip install sentence-transformers numpy"
			)
			raise ValueError(msg)

		# Try to load the model using the instance method
		with loading_spinner("Loading embedding model..."):
			# Use self._check_model_availability() - it uses self.model_name internally
			if not self.__class__.is_model_available():
				self._check_model_availability()

		if not self.__class__.is_model_available():
			msg = "Semantic splitting failed: embedding model could not be loaded. Check logs for details."
			raise ValueError(msg)

		try:
			chunks = self._split_semantic(diff)

			# If we truncated the content, restore the original content for the actual chunks
			if diff.content and chunks:
				# Create a mapping of file paths to chunks for quick lookup
				chunks_by_file = {}
				for chunk in chunks:
					for file_path in chunk.files:
						if file_path not in chunks_by_file:
							chunks_by_file[file_path] = []
						chunks_by_file[file_path].append(chunk)

				# For chunks that represent files we can find in the original content,
				# update their content to include the full original diff for that file
				for chunk in chunks:
					# Use a heuristic to match file sections in the original content
					for file_path in chunk.files:
						file_marker = f"diff --git a/{file_path} b/{file_path}"
						if file_marker in diff.content:
							# Found a match for this file in the original content
							# Extract that file's complete diff section
							start_idx = diff.content.find(file_marker)
							end_idx = diff.content.find("diff --git", start_idx + len(file_marker))
							if end_idx == -1:  # Last file in the diff
								end_idx = len(diff.content)

							file_diff = diff.content[start_idx:end_idx].strip()

							# Now replace just this file's content in the chunk
							# This is a heuristic that may need adjustment based on your diff format
							if chunk.content and file_marker in chunk.content:
								chunk_start = chunk.content.find(file_marker)
								chunk_end = chunk.content.find("diff --git", chunk_start + len(file_marker))
								if chunk_end == -1:  # Last file in the chunk
									chunk_end = len(chunk.content)

								# Replace this file's truncated diff with the full diff
								chunk.content = chunk.content[:chunk_start] + file_diff + chunk.content[chunk_end:]

			return chunks, []
		except Exception as e:
			logger.exception("Semantic splitting failed")
			console.print(f"[red]Semantic splitting failed: {e}[/red]")

			# Try basic splitting as a fallback
			logger.warning("Falling back to basic file splitting")
			console.print("[yellow]Falling back to basic file splitting[/yellow]")
			# Return empty list for filtered_large_files as it's no longer tracked here
			return self._create_basic_file_chunk(diff), []

	def _create_basic_file_chunk(self, diff: GitDiff) -> list[DiffChunk]:
		"""
		Create a basic chunk per file without semantic analysis.

		Args:
		    diff: GitDiff object to split

		Returns:
		    List of DiffChunk objects, one per file

		"""
		chunks = []

		if diff.files:
			# Create a basic chunk, one per file in this strategy, no semantic grouping
			strategy = FileSplitStrategy()
			chunks = strategy.split(diff)

		return chunks

	def _split_semantic(self, diff: GitDiff) -> list[DiffChunk]:
		"""
		Perform semantic splitting, falling back if needed.

		Args:
		    diff: GitDiff object to split

		Returns:
		    List of DiffChunk objects

		Raises:
		    ValueError: If semantic splitting fails and fallback is not possible.

		"""
		if not self.are_sentence_transformers_available():
			logger.warning("Sentence transformers unavailable. Falling back to file-based splitting.")
			# Directly use FileSplitStrategy when ST is unavailable
			file_splitter = FileSplitStrategy()
			return file_splitter.split(diff)

		# Existing logic for semantic splitting when ST is available
		try:
			semantic_strategy = SemanticSplitStrategy(embedding_model=self._embedding_model)
			return semantic_strategy.split(diff)
		except Exception:
			logger.exception("Semantic splitting failed: %s. Falling back to file splitting.")
			# Fallback to FileSplitStrategy on any semantic splitting error
			file_splitter = FileSplitStrategy()
			return file_splitter.split(diff)

	def _calculate_semantic_similarity(self, text1: str, text2: str) -> float:
		"""
		Calculate semantic similarity between two texts using the embedding model.

		Args:
		    text1: First text
		    text2: Second text

		Returns:
		    Similarity score between 0 and 1

		"""
		# Check if embedding model is available
		if not self.__class__.are_sentence_transformers_available():
			logger.debug("Sentence transformers not available, returning zero similarity")
			return 0.0

		# Call instance method self._check_model_availability()
		if not self.__class__.is_model_available():
			self._check_model_availability()

		if not self.__class__.is_model_available() or self.__class__.get_embedding_model() is None:
			logger.debug("Embedding model not available, returning zero similarity")
			return 0.0

		# Assign to local variable after check guarantees it's not None
		embedding_model_maybe_none = self.__class__.get_embedding_model()
		if embedding_model_maybe_none is None:
			# This case should have been caught earlier, but log just in case
			logger.error("Embedding model unexpectedly None after availability check")
			return 0.0

		embedding_model = embedding_model_maybe_none  # Now we know it's not None

		try:
			# Get embeddings for both texts
			emb1 = embedding_model.encode([text1])[0]
			emb2 = embedding_model.encode([text2])[0]

			# Calculate similarity using numpy
			return calculate_semantic_similarity(emb1.tolist(), emb2.tolist())
		except (ValueError, TypeError, IndexError, RuntimeError) as e:
			logger.warning("Failed to calculate semantic similarity: %s", e)
			return 0.0

	def encode_chunks(self, chunks: list[str]) -> dict[str, np.ndarray]:
		"""
		Encode a list of text chunks using the embedding model.

		Args:
		    chunks: List of text chunks to encode

		Returns:
		    Dictionary with embeddings array

		"""
		# Ensure the model is initialized
		if self.__class__.are_sentence_transformers_available() and not self.__class__.is_model_available():
			self._check_model_availability()

		if not self.__class__.is_model_available():
			logger.debug("Embedding model not available, returning empty embeddings")
			return {"embeddings": np.array([])}

		# Skip empty chunks
		if not chunks:
			logger.debug("No chunks to encode")
			return {"embeddings": np.array([])}

		# Use class method for class cache access
		if self.__class__.get_embedding_model() is None:
			logger.debug("Embedding model is None but was marked as available, reinitializing")
			# Re-check availability using instance method
			self._check_model_availability()

		# Check again after potential re-initialization and assign to local variable
		if self.__class__.get_embedding_model() is None:
			logger.error("Embedding model is still None after re-check")
			return {"embeddings": np.array([])}

		# Explicitly cast after the check
		embedding_model_maybe_none = self.__class__.get_embedding_model()
		if embedding_model_maybe_none is None:
			logger.error("Embedding model unexpectedly None in encode_chunks")
			return {"embeddings": np.array([])}

		embedding_model = embedding_model_maybe_none  # Now we know it's not None

		try:
			logger.debug("Encoding %d chunks", len(chunks))
			embeddings = embedding_model.encode(chunks)
			logger.debug("Successfully encoded %d chunks to shape %s", len(chunks), embeddings.shape)
			return {"embeddings": embeddings}
		except Exception:
			logger.exception("Error encoding chunks")
			return {"embeddings": np.array([])}  # Return empty on error

__init__

__init__(
	repo_root: Path,
	similarity_threshold: float = DEFAULT_CONFIG["commit"][
		"diff_splitter"
	]["similarity_threshold"],
	directory_similarity_threshold: float = DEFAULT_CONFIG[
		"commit"
	]["diff_splitter"]["directory_similarity_threshold"],
	min_chunks_for_consolidation: int = DEFAULT_CONFIG[
		"commit"
	]["diff_splitter"]["min_chunks_for_consolidation"],
	max_chunks_before_consolidation: int = DEFAULT_CONFIG[
		"commit"
	]["diff_splitter"]["max_chunks_before_consolidation"],
	max_file_size_for_llm: int = DEFAULT_CONFIG["commit"][
		"diff_splitter"
	]["max_file_size_for_llm"],
	max_log_diff_size: int = DEFAULT_CONFIG["commit"][
		"diff_splitter"
	]["max_log_diff_size"],
	model_name: str = DEFAULT_CONFIG["commit"][
		"diff_splitter"
	]["model_name"],
) -> None

Initialize the diff splitter.

Parameters:

Name	Type	Description	Default
repo_root	Path	Root directory of the Git repository	required
similarity_threshold	float	Threshold for grouping by content similarity.	DEFAULT_CONFIG['commit']['diff_splitter']['similarity_threshold']
directory_similarity_threshold	float	Threshold for directory similarity.	DEFAULT_CONFIG['commit']['diff_splitter']['directory_similarity_threshold']
min_chunks_for_consolidation	int	Min chunks to trigger consolidation.	DEFAULT_CONFIG['commit']['diff_splitter']['min_chunks_for_consolidation']
max_chunks_before_consolidation	int	Max chunks allowed before forced consolidation.	DEFAULT_CONFIG['commit']['diff_splitter']['max_chunks_before_consolidation']
max_file_size_for_llm	int	Max file size (bytes) to process for LLM context. Defaults to value from DEFAULT_CONFIG["commit"]["diff_splitter"]["max_file_size_for_llm"] if None.	DEFAULT_CONFIG['commit']['diff_splitter']['max_file_size_for_llm']
max_log_diff_size	int	Max diff size (bytes) to log in debug mode. Defaults to value from DEFAULT_CONFIG["commit"]["diff_splitter"]["max_log_diff_size"] if None.	DEFAULT_CONFIG['commit']['diff_splitter']['max_log_diff_size']
model_name	str	Name of the sentence-transformer model to use. Defaults to value from DEFAULT_CONFIG["commit"]["diff_splitter"]["model_name"] if None.	DEFAULT_CONFIG['commit']['diff_splitter']['model_name']

Source code in src/codemap/git/diff_splitter/splitter.py

def __init__(
	self,
	repo_root: Path,
	# Defaults are now sourced from DEFAULT_CONFIG
	similarity_threshold: float = DEFAULT_CONFIG["commit"]["diff_splitter"]["similarity_threshold"],
	directory_similarity_threshold: float = DEFAULT_CONFIG["commit"]["diff_splitter"][
		"directory_similarity_threshold"
	],
	min_chunks_for_consolidation: int = DEFAULT_CONFIG["commit"]["diff_splitter"]["min_chunks_for_consolidation"],
	max_chunks_before_consolidation: int = DEFAULT_CONFIG["commit"]["diff_splitter"][
		"max_chunks_before_consolidation"
	],
	max_file_size_for_llm: int = DEFAULT_CONFIG["commit"]["diff_splitter"]["max_file_size_for_llm"],
	max_log_diff_size: int = DEFAULT_CONFIG["commit"]["diff_splitter"]["max_log_diff_size"],
	model_name: str = DEFAULT_CONFIG["commit"]["diff_splitter"]["model_name"],
) -> None:
	"""
	Initialize the diff splitter.

	Args:
	    repo_root: Root directory of the Git repository
	    similarity_threshold: Threshold for grouping by content similarity.
	    directory_similarity_threshold: Threshold for directory similarity.
	    min_chunks_for_consolidation: Min chunks to trigger consolidation.
	    max_chunks_before_consolidation: Max chunks allowed before forced consolidation.
	    max_file_size_for_llm: Max file size (bytes) to process for LLM context.
	        Defaults to value from `DEFAULT_CONFIG["commit"]["diff_splitter"]["max_file_size_for_llm"]` if None.
	    max_log_diff_size: Max diff size (bytes) to log in debug mode.
	        Defaults to value from `DEFAULT_CONFIG["commit"]["diff_splitter"]["max_log_diff_size"]` if None.
	    model_name: Name of the sentence-transformer model to use.
	        Defaults to value from `DEFAULT_CONFIG["commit"]["diff_splitter"]["model_name"]` if None.

	"""
	self.repo_root = repo_root
	# Store thresholds
	self.similarity_threshold = similarity_threshold
	self.directory_similarity_threshold = directory_similarity_threshold
	self.min_chunks_for_consolidation = min_chunks_for_consolidation
	self.max_chunks_before_consolidation = max_chunks_before_consolidation
	# Store other settings
	self.max_file_size_for_llm = max_file_size_for_llm
	self.max_log_diff_size = max_log_diff_size
	self.model_name = model_name

repo_root instance-attribute

repo_root = repo_root

similarity_threshold instance-attribute

similarity_threshold = similarity_threshold

directory_similarity_threshold instance-attribute

directory_similarity_threshold = (
	directory_similarity_threshold
)

min_chunks_for_consolidation instance-attribute

min_chunks_for_consolidation = min_chunks_for_consolidation

max_chunks_before_consolidation instance-attribute

max_chunks_before_consolidation = (
	max_chunks_before_consolidation
)

max_file_size_for_llm instance-attribute

max_file_size_for_llm = max_file_size_for_llm

max_log_diff_size instance-attribute

max_log_diff_size = max_log_diff_size

model_name instance-attribute

model_name = model_name

are_sentence_transformers_available classmethod

are_sentence_transformers_available() -> bool

Check if sentence transformers are available.

Returns:

Type	Description
bool	True if sentence transformers are available, False otherwise

Source code in src/codemap/git/diff_splitter/splitter.py

@classmethod
def are_sentence_transformers_available(cls) -> bool:
	"""
	Check if sentence transformers are available.

	Returns:
	    True if sentence transformers are available, False otherwise

	"""
	return cls._sentence_transformers_available or cls._check_sentence_transformers_availability()

is_model_available classmethod

is_model_available() -> bool

Check if embedding model is available.

Returns:

Type	Description
bool	True if embedding model is available, False otherwise

Source code in src/codemap/git/diff_splitter/splitter.py

@classmethod
def is_model_available(cls) -> bool:
	"""
	Check if embedding model is available.

	Returns:
	    True if embedding model is available, False otherwise

	"""
	return bool(cls._model_available)

set_model_available classmethod

set_model_available(value: bool) -> None

Set model availability flag.

Parameters:

Name	Type	Description	Default
value	bool	Boolean indicating if model is available	required

Source code in src/codemap/git/diff_splitter/splitter.py

@classmethod
def set_model_available(cls, value: bool) -> None:
	"""
	Set model availability flag.

	Args:
	    value: Boolean indicating if model is available

	"""
	cls._model_available = value

get_embedding_model classmethod

get_embedding_model() -> EmbeddingModel | None

Get the embedding model.

Returns:

Type	Description
EmbeddingModel | None	The embedding model or None if not available

Source code in src/codemap/git/diff_splitter/splitter.py

@classmethod
def get_embedding_model(cls) -> EmbeddingModel | None:
	"""
	Get the embedding model.

	Returns:
	    The embedding model or None if not available

	"""
	return cls._embedding_model

set_embedding_model classmethod

set_embedding_model(model: EmbeddingModel) -> None

Set the embedding model.

Parameters:

Name	Type	Description	Default
model	EmbeddingModel	The embedding model to set	required

Source code in src/codemap/git/diff_splitter/splitter.py

@classmethod
def set_embedding_model(cls, model: EmbeddingModel) -> None:
	"""
	Set the embedding model.

	Args:
	    model: The embedding model to set

	"""
	cls._embedding_model = model

split_diff

split_diff(
	diff: GitDiff,
) -> tuple[list[DiffChunk], list[str]]

Split a diff into logical chunks using semantic splitting.

Parameters:

Name	Type	Description	Default
diff	GitDiff	GitDiff object to split	required

Returns:

Type	Description
tuple[list[DiffChunk], list[str]]	Tuple of (List of DiffChunk objects based on semantic analysis, List of filtered large files)

Raises:

Type	Description
ValueError	If semantic splitting is not available or fails

Source code in src/codemap/git/diff_splitter/splitter.py

def split_diff(self, diff: GitDiff) -> tuple[list[DiffChunk], list[str]]:
	"""
	Split a diff into logical chunks using semantic splitting.

	Args:
	    diff: GitDiff object to split

	Returns:
	    Tuple of (List of DiffChunk objects based on semantic analysis, List of filtered large files)

	Raises:
	    ValueError: If semantic splitting is not available or fails

	"""
	if not diff.files:
		return [], []

	# Special handling for untracked files - bypass semantic split since the content isn't a proper diff format
	if diff.is_untracked:
		logger.debug("Processing untracked files with special handling: %d files", len(diff.files))
		# Create a simple chunk per file to avoid errors with unidiff parsing
		chunks = []
		for file_path in diff.files:
			# Create a basic chunk with file info but without trying to parse the content as a diff
			chunks = [
				DiffChunk(
					files=[file_path],
					content=f"New untracked file: {file_path}",
					description=f"New file: {file_path}",
				)
				for file_path in diff.files
			]
		return chunks, []

	# In test environments, log the diff content for debugging
	if is_test_environment():
		logger.debug("Processing diff in test environment with %d files", len(diff.files) if diff.files else 0)
		if diff.content and len(diff.content) < self.max_log_diff_size:  # Use configured max log size
			logger.debug("Diff content: %s", diff.content)

	# Process files in the diff
	if diff.files:
		# Filter for valid files (existence, tracked status), max_size check removed here
		diff.files, _ = filter_valid_files(diff.files, is_test_environment())
		# filtered_large_files list is no longer populated or used here

	if not diff.files:
		logger.warning("No valid files to process after filtering")
		return [], []  # Return empty lists

	# Set up availability flags if not already set
	# Use class method to check sentence transformers availability
	if not self.__class__.are_sentence_transformers_available():
		msg = (
			"Semantic splitting is not available. sentence-transformers package is required. "
			"Install with: pip install sentence-transformers numpy"
		)
		raise ValueError(msg)

	# Try to load the model using the instance method
	with loading_spinner("Loading embedding model..."):
		# Use self._check_model_availability() - it uses self.model_name internally
		if not self.__class__.is_model_available():
			self._check_model_availability()

	if not self.__class__.is_model_available():
		msg = "Semantic splitting failed: embedding model could not be loaded. Check logs for details."
		raise ValueError(msg)

	try:
		chunks = self._split_semantic(diff)

		# If we truncated the content, restore the original content for the actual chunks
		if diff.content and chunks:
			# Create a mapping of file paths to chunks for quick lookup
			chunks_by_file = {}
			for chunk in chunks:
				for file_path in chunk.files:
					if file_path not in chunks_by_file:
						chunks_by_file[file_path] = []
					chunks_by_file[file_path].append(chunk)

			# For chunks that represent files we can find in the original content,
			# update their content to include the full original diff for that file
			for chunk in chunks:
				# Use a heuristic to match file sections in the original content
				for file_path in chunk.files:
					file_marker = f"diff --git a/{file_path} b/{file_path}"
					if file_marker in diff.content:
						# Found a match for this file in the original content
						# Extract that file's complete diff section
						start_idx = diff.content.find(file_marker)
						end_idx = diff.content.find("diff --git", start_idx + len(file_marker))
						if end_idx == -1:  # Last file in the diff
							end_idx = len(diff.content)

						file_diff = diff.content[start_idx:end_idx].strip()

						# Now replace just this file's content in the chunk
						# This is a heuristic that may need adjustment based on your diff format
						if chunk.content and file_marker in chunk.content:
							chunk_start = chunk.content.find(file_marker)
							chunk_end = chunk.content.find("diff --git", chunk_start + len(file_marker))
							if chunk_end == -1:  # Last file in the chunk
								chunk_end = len(chunk.content)

							# Replace this file's truncated diff with the full diff
							chunk.content = chunk.content[:chunk_start] + file_diff + chunk.content[chunk_end:]

		return chunks, []
	except Exception as e:
		logger.exception("Semantic splitting failed")
		console.print(f"[red]Semantic splitting failed: {e}[/red]")

		# Try basic splitting as a fallback
		logger.warning("Falling back to basic file splitting")
		console.print("[yellow]Falling back to basic file splitting[/yellow]")
		# Return empty list for filtered_large_files as it's no longer tracked here
		return self._create_basic_file_chunk(diff), []

encode_chunks

encode_chunks(chunks: list[str]) -> dict[str, ndarray]

Encode a list of text chunks using the embedding model.

Parameters:

Name	Type	Description	Default
chunks	list[str]	List of text chunks to encode	required

Returns:

Type	Description
dict[str, ndarray]	Dictionary with embeddings array

Source code in src/codemap/git/diff_splitter/splitter.py

def encode_chunks(self, chunks: list[str]) -> dict[str, np.ndarray]:
	"""
	Encode a list of text chunks using the embedding model.

	Args:
	    chunks: List of text chunks to encode

	Returns:
	    Dictionary with embeddings array

	"""
	# Ensure the model is initialized
	if self.__class__.are_sentence_transformers_available() and not self.__class__.is_model_available():
		self._check_model_availability()

	if not self.__class__.is_model_available():
		logger.debug("Embedding model not available, returning empty embeddings")
		return {"embeddings": np.array([])}

	# Skip empty chunks
	if not chunks:
		logger.debug("No chunks to encode")
		return {"embeddings": np.array([])}

	# Use class method for class cache access
	if self.__class__.get_embedding_model() is None:
		logger.debug("Embedding model is None but was marked as available, reinitializing")
		# Re-check availability using instance method
		self._check_model_availability()

	# Check again after potential re-initialization and assign to local variable
	if self.__class__.get_embedding_model() is None:
		logger.error("Embedding model is still None after re-check")
		return {"embeddings": np.array([])}

	# Explicitly cast after the check
	embedding_model_maybe_none = self.__class__.get_embedding_model()
	if embedding_model_maybe_none is None:
		logger.error("Embedding model unexpectedly None in encode_chunks")
		return {"embeddings": np.array([])}

	embedding_model = embedding_model_maybe_none  # Now we know it's not None

	try:
		logger.debug("Encoding %d chunks", len(chunks))
		embeddings = embedding_model.encode(chunks)
		logger.debug("Successfully encoded %d chunks to shape %s", len(chunks), embeddings.shape)
		return {"embeddings": embeddings}
	except Exception:
		logger.exception("Error encoding chunks")
		return {"embeddings": np.array([])}  # Return empty on error

BaseSplitStrategy

Base class for diff splitting strategies.

Source code in src/codemap/git/diff_splitter/strategies.py

class BaseSplitStrategy:
	"""Base class for diff splitting strategies."""

	def __init__(self, embedding_model: EmbeddingModel | None = None) -> None:
		"""Initialize with optional embedding model."""
		self._embedding_model = embedding_model
		# Precompile regex patterns for better performance
		self._file_pattern = re.compile(r"diff --git a/.*? b/(.*?)\n")
		self._hunk_pattern = re.compile(r"@@ -\d+,\d+ \+\d+,\d+ @@")

	def split(self, diff: GitDiff) -> list[DiffChunk]:
		"""
		Split the diff into chunks.

		Args:
		    diff: GitDiff object to split

		Returns:
		    List of DiffChunk objects

		"""
		msg = "Subclasses must implement this method"
		raise NotImplementedError(msg)

__init__

__init__(
	embedding_model: EmbeddingModel | None = None,
) -> None

Initialize with optional embedding model.

Source code in src/codemap/git/diff_splitter/strategies.py

def __init__(self, embedding_model: EmbeddingModel | None = None) -> None:
	"""Initialize with optional embedding model."""
	self._embedding_model = embedding_model
	# Precompile regex patterns for better performance
	self._file_pattern = re.compile(r"diff --git a/.*? b/(.*?)\n")
	self._hunk_pattern = re.compile(r"@@ -\d+,\d+ \+\d+,\d+ @@")

split

split(diff: GitDiff) -> list[DiffChunk]

Split the diff into chunks.

Parameters:

Name	Type	Description	Default
diff	GitDiff	GitDiff object to split	required

Returns:

Type	Description
list[DiffChunk]	List of DiffChunk objects

Source code in src/codemap/git/diff_splitter/strategies.py

def split(self, diff: GitDiff) -> list[DiffChunk]:
	"""
	Split the diff into chunks.

	Args:
	    diff: GitDiff object to split

	Returns:
	    List of DiffChunk objects

	"""
	msg = "Subclasses must implement this method"
	raise NotImplementedError(msg)

FileSplitStrategy

Bases: BaseSplitStrategy

Strategy to split diffs by file.

Source code in src/codemap/git/diff_splitter/strategies.py

class FileSplitStrategy(BaseSplitStrategy):
	"""Strategy to split diffs by file."""

	def split(self, diff: GitDiff) -> list[DiffChunk]:
		"""
		Split a diff into chunks by file.

		Args:
		    diff: GitDiff object to split

		Returns:
		    List of DiffChunk objects, one per file

		"""
		if not diff.content:
			return self._handle_empty_diff_content(diff)

		# Split the diff content by file
		file_chunks = self._file_pattern.split(diff.content)[1:]  # Skip first empty chunk

		# Group files with their content
		chunks = []
		for i in range(0, len(file_chunks), 2):
			if i + 1 >= len(file_chunks):
				break

			file_name = file_chunks[i]
			content = file_chunks[i + 1]

			if self._is_valid_filename(file_name) and content:
				diff_header = f"diff --git a/{file_name} b/{file_name}\n"
				chunks.append(
					DiffChunk(
						files=[file_name],
						content=diff_header + content,
						description=f"Changes in {file_name}",
					)
				)

		return chunks

	def _handle_empty_diff_content(self, diff: GitDiff) -> list[DiffChunk]:
		"""Handle untracked files in empty diff content."""
		if (not diff.is_staged or diff.is_untracked) and diff.files:
			# Filter out invalid file names
			valid_files = [file for file in diff.files if self._is_valid_filename(file)]
			return [DiffChunk(files=[f], content="", description=f"New file: {f}") for f in valid_files]
		return []

	@staticmethod
	def _is_valid_filename(filename: str) -> bool:
		"""Check if the filename is valid (not a pattern or template)."""
		if not filename:
			return False
		invalid_chars = ["*", "+", "{", "}", "\\"]
		return not (any(char in filename for char in invalid_chars) or filename.startswith('"'))

split

split(diff: GitDiff) -> list[DiffChunk]

Split a diff into chunks by file.

Parameters:

Name	Type	Description	Default
diff	GitDiff	GitDiff object to split	required

Returns:

Type	Description
list[DiffChunk]	List of DiffChunk objects, one per file

Source code in src/codemap/git/diff_splitter/strategies.py

def split(self, diff: GitDiff) -> list[DiffChunk]:
	"""
	Split a diff into chunks by file.

	Args:
	    diff: GitDiff object to split

	Returns:
	    List of DiffChunk objects, one per file

	"""
	if not diff.content:
		return self._handle_empty_diff_content(diff)

	# Split the diff content by file
	file_chunks = self._file_pattern.split(diff.content)[1:]  # Skip first empty chunk

	# Group files with their content
	chunks = []
	for i in range(0, len(file_chunks), 2):
		if i + 1 >= len(file_chunks):
			break

		file_name = file_chunks[i]
		content = file_chunks[i + 1]

		if self._is_valid_filename(file_name) and content:
			diff_header = f"diff --git a/{file_name} b/{file_name}\n"
			chunks.append(
				DiffChunk(
					files=[file_name],
					content=diff_header + content,
					description=f"Changes in {file_name}",
				)
			)

	return chunks

SemanticSplitStrategy

Bases: BaseSplitStrategy

Strategy to split diffs semantically.

Source code in src/codemap/git/diff_splitter/strategies.py

class SemanticSplitStrategy(BaseSplitStrategy):
	"""Strategy to split diffs semantically."""

	def __init__(
		self,
		embedding_model: EmbeddingModel | None = None,
		code_extensions: set[str] | None = None,
		related_file_patterns: list[tuple[Pattern, Pattern]] | None = None,
		similarity_threshold: float = 0.4,
		directory_similarity_threshold: float = 0.3,
		min_chunks_for_consolidation: int = 2,
		max_chunks_before_consolidation: int = 20,
		max_file_size_for_llm: int | None = None,
	) -> None:
		"""
		Initialize the SemanticSplitStrategy.

		Args:
		    embedding_model: Optional embedding model instance
		    code_extensions: Optional set of code file extensions. Defaults to config.
		    related_file_patterns: Optional list of related file patterns
		    similarity_threshold: Threshold for grouping by content similarity.
		    directory_similarity_threshold: Threshold for directory similarity.
		    min_chunks_for_consolidation: Min chunks to trigger consolidation.
		    max_chunks_before_consolidation: Max chunks allowed before forced consolidation.
		    max_file_size_for_llm: Max file size for LLM processing.

		"""
		super().__init__(embedding_model)
		# Store thresholds and settings
		self.similarity_threshold = similarity_threshold
		self.directory_similarity_threshold = directory_similarity_threshold
		self.min_chunks_for_consolidation = min_chunks_for_consolidation
		self.max_chunks_before_consolidation = max_chunks_before_consolidation
		# Use default from config if not provided
		self.max_file_size_for_llm = (
			max_file_size_for_llm
			if max_file_size_for_llm is not None
			else DEFAULT_CONFIG["commit"]["diff_splitter"]["max_file_size_for_llm"]
		)

		# Set up file extensions, defaulting to config if None is passed
		self.code_extensions = (
			code_extensions
			if code_extensions is not None
			else set(DEFAULT_CONFIG["commit"]["diff_splitter"]["default_code_extensions"])
		)
		# Initialize patterns for related files
		self.related_file_patterns = related_file_patterns or self._initialize_related_file_patterns()

	def split(self, diff: GitDiff) -> list[DiffChunk]:
		"""
		Split a diff into chunks based on semantic relationships.

		Args:
		    diff: GitDiff object to split

		Returns:
		    List of DiffChunk objects based on semantic analysis

		"""
		if not diff.files:
			logger.debug("No files to process")
			return []

		# Validate embedding model is available
		self._validate_embedding_model()

		# Handle files in manageable groups
		if len(diff.files) > MAX_FILES_PER_GROUP:
			logger.info("Processing large number of files (%d) in smaller groups", len(diff.files))

			# Group files by directory to increase likelihood of related files being processed together
			files_by_dir = {}
			for file in diff.files:
				dir_path = str(Path(file).parent)
				if dir_path not in files_by_dir:
					files_by_dir[dir_path] = []
				files_by_dir[dir_path].append(file)

			# Process each directory group separately, keeping chunks under 5 files
			all_chunks = []
			# Iterate directly over the file lists since the directory path isn't used here
			for files in files_by_dir.values():
				# Process files in this directory in batches of 3-5
				for i in range(0, len(files), 3):
					batch = files[i : i + 3]
					# Create a new GitDiff for the batch, ensuring content is passed
					batch_diff = GitDiff(
						files=batch,
						content=diff.content,  # Pass the original full diff content
						is_staged=diff.is_staged,
					)
					all_chunks.extend(self._process_group(batch_diff))

			return all_chunks

		# For smaller groups, process normally
		return self._process_group(diff)

	def _process_group(self, diff: GitDiff) -> list[DiffChunk]:
		"""
		Process a GitDiff with one or more files.

		Originally designed for single files, but now supports multiple files.

		"""
		if not diff.files:
			logger.warning("_process_group called with empty files list")
			return []

		# If multiple files, this used to log an error, but now we'll handle it properly
		if len(diff.files) > 1:
			logger.debug("Processing group with multiple files: %s", diff.files)

			# Extract content for each file individually if possible
			chunks = []
			for file_path in diff.files:
				# Try to extract just this file's diff from the full content
				file_diff_content = self._extract_file_diff(diff.content, file_path)

				if file_diff_content:
					# Create a new diff for just this file
					file_diff = GitDiff(files=[file_path], content=file_diff_content, is_staged=diff.is_staged)
					# Process it and add the resulting chunks
					enhanced_chunks = self._enhance_semantic_split(file_diff)
					chunks.extend(enhanced_chunks)
				else:
					# If we couldn't extract just this file's diff, create a simple chunk
					chunks.append(
						DiffChunk(
							files=[file_path],
							content="",  # Empty content as we couldn't extract it
							description=f"Changes in {file_path}",
						)
					)

			# If we couldn't create any valid chunks, fallback to the original behavior
			if not chunks:
				return [DiffChunk(files=diff.files, content=diff.content, description="Multiple file changes")]

			return chunks

		# Original behavior for single file
		file_path = diff.files[0]

		# Enhance this single file diff
		enhanced_chunks = self._enhance_semantic_split(diff)  # Pass the original diff directly

		if not enhanced_chunks:
			logger.warning("No chunk generated for file: %s after enhancement.", file_path)
			# Fallback if enhancement yields nothing
			enhanced_chunks = [
				DiffChunk(
					files=[file_path],
					content=diff.content,
					description=f"Changes in {file_path} (enhancement failed)",
				)
			]

		# No further consolidation or grouping needed here as we process file-by-file now
		return enhanced_chunks

	def _extract_file_diff(self, full_diff_content: str, file_path: str) -> str:
		"""
		Extract the diff content for a specific file from a multi-file diff.

		Args:
		        full_diff_content: Complete diff content with multiple files
		        file_path: Path of the file to extract

		Returns:
		        The extracted diff for the specific file, or empty string if not found

		"""
		import re

		# Pattern to match the start of a diff for a file
		diff_start_pattern = re.compile(r"diff --git a/([^\s]+) b/([^\s]+)")

		# Find all diff start positions
		diff_positions = []
		for match in diff_start_pattern.finditer(full_diff_content):
			_, b_file = match.groups()
			# For most changes both files are the same; for renames prefer b_file
			target_file = b_file
			diff_positions.append((match.start(), target_file))

		# Sort by position
		diff_positions.sort()

		# Find the diff for our file
		file_diff = ""
		for i, (start_pos, diff_file) in enumerate(diff_positions):
			if diff_file == file_path:
				# Found our file, now find the end
				if i < len(diff_positions) - 1:
					end_pos = diff_positions[i + 1][0]
					file_diff = full_diff_content[start_pos:end_pos]
				else:
					# Last file in the diff
					file_diff = full_diff_content[start_pos:]
				break

		return file_diff

	def _validate_embedding_model(self) -> None:
		"""Validate that the embedding model is available."""
		if self._embedding_model is None and not is_test_environment():
			msg = (
				"Semantic analysis unavailable: embedding model not available. "
				"Make sure the model is properly loaded before calling this method."
			)
			raise ValueError(msg)

	def _group_chunks_by_directory(self, chunks: list[DiffChunk]) -> dict[str, list[DiffChunk]]:
		"""Group chunks by their containing directory."""
		dir_groups: dict[str, list[DiffChunk]] = {}

		for chunk in chunks:
			if not chunk.files:
				continue

			file_path = chunk.files[0]
			dir_path = file_path.rsplit("/", 1)[0] if "/" in file_path else "root"

			if dir_path not in dir_groups:
				dir_groups[dir_path] = []

			dir_groups[dir_path].append(chunk)

		return dir_groups

	def _process_directory_group(
		self, chunks: list[DiffChunk], processed_files: set[str], semantic_chunks: list[DiffChunk]
	) -> None:
		"""Process chunks in a single directory group."""
		if len(chunks) == 1:
			# If only one file in directory, add it directly
			semantic_chunks.append(chunks[0])
			if chunks[0].files:
				processed_files.update(chunks[0].files)
		else:
			# For directories with multiple files, try to group them
			dir_processed: set[str] = set()

			# First try to group by related file patterns
			self._group_related_files(chunks, dir_processed, semantic_chunks)

			# Then try to group remaining files by content similarity
			remaining_chunks = [c for c in chunks if not c.files or c.files[0] not in dir_processed]

			if remaining_chunks:
				# Use default similarity threshold instead
				self._group_by_content_similarity(remaining_chunks, semantic_chunks)

			# Add all processed files to the global processed set
			processed_files.update(dir_processed)

	def _process_remaining_chunks(
		self, all_chunks: list[DiffChunk], processed_files: set[str], semantic_chunks: list[DiffChunk]
	) -> None:
		"""Process any remaining chunks that weren't grouped by directory."""
		remaining_chunks = [c for c in all_chunks if c.files and c.files[0] not in processed_files]

		if remaining_chunks:
			self._group_by_content_similarity(remaining_chunks, semantic_chunks)

	def _consolidate_if_needed(self, semantic_chunks: list[DiffChunk]) -> list[DiffChunk]:
		"""Consolidate chunks if we have too many small ones."""
		has_single_file_chunks = any(len(chunk.files) == 1 for chunk in semantic_chunks)

		if len(semantic_chunks) > self.max_chunks_before_consolidation and has_single_file_chunks:
			return self._consolidate_small_chunks(semantic_chunks)

		return semantic_chunks

	@staticmethod
	def _initialize_related_file_patterns() -> list[tuple[Pattern, Pattern]]:
		"""
		Initialize and compile regex patterns for related files.

		Returns:
		    List of compiled regex pattern pairs

		"""
		# Pre-compile regex for efficiency and validation
		related_file_patterns = []
		# Define patterns using standard strings with escaped backreferences
		default_patterns: list[tuple[str, str]] = [
			# --- General Code + Test Files ---
			# Python
			("^(.*)\\.py$", "\\\\1_test\\.py$"),
			("^(.*)\\.py$", "test_\\\\1\\.py$"),
			("^(.*)\\.(py)$", "\\\\1_test\\.\\\\2$"),  # For file.py and file_test.py pattern
			("^(.*)\\.(py)$", "\\\\1Test\\.\\\\2$"),  # For file.py and fileTest.py pattern
			("^(.*)\\.py$", "\\\\1_spec\\.py$"),
			("^(.*)\\.py$", "spec_\\\\1\\.py$"),
			# JavaScript / TypeScript (including JSX/TSX)
			("^(.*)\\.(js|jsx|ts|tsx)$", "\\\\1\\.(test|spec)\\.(js|jsx|ts|tsx)$"),
			("^(.*)\\.(js|jsx|ts|tsx)$", "\\\\1\\.stories\\.(js|jsx|ts|tsx)$"),  # Storybook
			("^(.*)\\.(js|ts)$", "\\\\1\\.d\\.ts$"),  # JS/TS + Declaration files
			# Ruby
			("^(.*)\\.rb$", "\\\\1_spec\\.rb$"),
			("^(.*)\\.rb$", "\\\\1_test\\.rb$"),
			("^(.*)\\.rb$", "spec/.*_spec\\.rb$"),  # Common RSpec structure
			# Java
			("^(.*)\\.java$", "\\\\1Test\\.java$"),
			("src/main/java/(.*)\\.java$", "src/test/java/\\\\1Test\\.java$"),  # Maven/Gradle structure
			# Go
			("^(.*)\\.go$", "\\\\1_test\\.go$"),
			# C#
			("^(.*)\\.cs$", "\\\\1Tests?\\.cs$"),
			# PHP
			("^(.*)\\.php$", "\\\\1Test\\.php$"),
			("^(.*)\\.php$", "\\\\1Spec\\.php$"),
			("src/(.*)\\.php$", "tests/\\\\1Test\\.php$"),  # Common structure
			# Rust
			("src/(lib|main)\\.rs$", "tests/.*\\.rs$"),  # Main/Lib and integration tests
			("src/(.*)\\.rs$", "src/\\\\1_test\\.rs$"),  # Inline tests (less common for grouping)
			# Swift
			("^(.*)\\.swift$", "\\\\1Tests?\\.swift$"),
			# Kotlin
			("^(.*)\\.kt$", "\\\\1Test\\.kt$"),
			("src/main/kotlin/(.*)\\.kt$", "src/test/kotlin/\\\\1Test\\.kt$"),  # Common structure
			# --- Frontend Component Bundles ---
			# JS/TS Components + Styles (CSS, SCSS, LESS, CSS Modules)
			("^(.*)\\.(js|jsx|ts|tsx)$", "\\\\1\\.(css|scss|less)$"),
			("^(.*)\\.(js|jsx|ts|tsx)$", "\\\\1\\.module\\.(css|scss|less)$"),
			("^(.*)\\.(js|jsx|ts|tsx)$", "\\\\1\\.styles?\\.(js|ts)$"),  # Styled Components / Emotion convention
			# Vue Components + Styles
			("^(.*)\\.vue$", "\\\\1\\.(css|scss|less)$"),
			("^(.*)\\.vue$", "\\\\1\\.module\\.(css|scss|less)$"),
			# Svelte Components + Styles/Scripts
			("^(.*)\\.svelte$", "\\\\1\\.(css|scss|less)$"),
			("^(.*)\\.svelte$", "\\\\1\\.(js|ts)$"),
			# Angular Components (more specific structure)
			("^(.*)\\.component\\.ts$", "\\\\1\\.component\\.html$"),
			("^(.*)\\.component\\.ts$", "\\\\1\\.component\\.(css|scss|less)$"),
			("^(.*)\\.component\\.ts$", "\\\\1\\.component\\.spec\\.ts$"),  # Component + its test
			("^(.*)\\.service\\.ts$", "\\\\1\\.service\\.spec\\.ts$"),  # Service + its test
			("^(.*)\\.module\\.ts$", "\\\\1\\.routing\\.module\\.ts$"),  # Module + routing
			# --- Implementation / Definition / Generation ---
			# C / C++ / Objective-C
			("^(.*)\\.h$", "\\\\1\\.c$"),
			("^(.*)\\.h$", "\\\\1\\.m$"),
			("^(.*)\\.hpp$", "\\\\1\\.cpp$"),
			("^(.*)\\.h$", "\\\\1\\.cpp$"),  # Allow .h with .cpp
			("^(.*)\\.h$", "\\\\1\\.mm$"),
			# Protocol Buffers / gRPC
			("^(.*)\\.proto$", "\\\\1\\.pb\\.(go|py|js|java|rb|cs|ts)$"),
			("^(.*)\\.proto$", "\\\\1_pb2?\\.py$"),  # Python specific proto generation
			("^(.*)\\.proto$", "\\\\1_grpc\\.pb\\.(go|js|ts)$"),  # gRPC specific
			# Interface Definition Languages (IDL)
			("^(.*)\\.idl$", "\\\\1\\.(h|cpp|cs|java)$"),
			# API Specifications (OpenAPI/Swagger)
			("(openapi|swagger)\\.(yaml|yml|json)$", ".*\\.(go|py|js|java|rb|cs|ts)$"),  # Spec + generated code
			("^(.*)\\.(yaml|yml|json)$", "\\\\1\\.generated\\.(go|py|js|java|rb|cs|ts)$"),  # Another convention
			# --- Web Development (HTML Centric) ---
			("^(.*)\\.html$", "\\\\1\\.(js|ts)$"),
			("^(.*)\\.html$", "\\\\1\\.(css|scss|less)$"),
			# --- Mobile Development ---
			# iOS (Swift)
			("^(.*)\\.swift$", "\\\\1\\.storyboard$"),
			("^(.*)\\.swift$", "\\\\1\\.xib$"),
			# Android (Kotlin/Java)
			("^(.*)\\.(kt|java)$", "res/layout/.*\\.(xml)$"),  # Code + Layout XML (Path sensitive)
			("AndroidManifest\\.xml$", ".*\\.(kt|java)$"),  # Manifest + Code
			("build\\.gradle(\\.kts)?$", ".*\\.(kt|java)$"),  # Gradle build + Code
			# --- Configuration Files ---
			# Package Managers
			("package\\.json$", "(package-lock\\.json|yarn\\.lock|pnpm-lock\\.yaml)$"),
			("requirements\\.txt$", "(setup\\.py|setup\\.cfg|pyproject\\.toml)$"),
			("pyproject\\.toml$", "(setup\\.py|setup\\.cfg|poetry\\.lock|uv\\.lock)$"),
			("Gemfile$", "Gemfile\\.lock$"),
			("Cargo\\.toml$", "Cargo\\.lock$"),
			("composer\\.json$", "composer\\.lock$"),  # PHP Composer
			("go\\.mod$", "go\\.sum$"),  # Go Modules
			("pom\\.xml$", ".*\\.java$"),  # Maven + Java
			("build\\.gradle(\\.kts)?$", ".*\\.(java|kt)$"),  # Gradle + Java/Kotlin
			# Linters / Formatters / Compilers / Type Checkers
			(
				"package\\.json$",
				"(tsconfig\\.json|\\.eslintrc(\\..*)?|\\.prettierrc(\\..*)?|\\.babelrc(\\..*)?|webpack\\.config\\.js|vite\\.config\\.(js|ts))$",
			),
			("pyproject\\.toml$", "(\\.flake8|\\.pylintrc|\\.isort\\.cfg|mypy\\.ini)$"),
			# Docker
			("Dockerfile$", "(\\.dockerignore|docker-compose\\.yml)$"),
			("docker-compose\\.yml$", "\\.env$"),
			# CI/CD
			("\\.github/workflows/.*\\.yml$", ".*\\.(sh|py|js|ts|go)$"),  # Workflow + scripts
			("\\.gitlab-ci\\.yml$", ".*\\.(sh|py|js|ts|go)$"),
			("Jenkinsfile$", ".*\\.(groovy|sh|py)$"),
			# IaC (Terraform)
			("^(.*)\\.tf$", "\\\\1\\.tfvars$"),
			("^(.*)\\.tf$", "\\\\1\\.tf$"),  # Group TF files together
			# --- Documentation ---
			("README\\.md$", ".*$"),  # README often updated with any change
			("^(.*)\\.md$", "\\\\1\\.(py|js|ts|go|java|rb|rs|php|swift|kt)$"),  # Markdown doc + related code
			("docs/.*\\.md$", "src/.*$"),  # Documentation in docs/ related to src/
			# --- Data Science / ML ---
			("^(.*)\\.ipynb$", "\\\\1\\.py$"),  # Notebook + Python script
			("^(.*)\\.py$", "data/.*\\.(csv|json|parquet)$"),  # Script + Data file (path sensitive)
			# --- General Fallbacks (Use with caution) ---
			# Files with same base name but different extensions (already covered by some specifics)
			# ("^(.*)\\..*$", "\\1\\..*$"), # Potentially too broad, rely on specifics above
		]

		for pattern1_str, pattern2_str in default_patterns:
			try:
				# Compile with IGNORECASE for broader matching
				pattern1 = re.compile(pattern1_str, re.IGNORECASE)
				pattern2 = re.compile(pattern2_str, re.IGNORECASE)
				related_file_patterns.append((pattern1, pattern2))
			except re.error as e:
				# Log only if pattern compilation fails
				logger.warning(f"Failed to compile regex pair: ({pattern1_str!r}, {pattern2_str!r}). Error: {e}")

		return related_file_patterns

	def _get_code_embedding(self, content: str) -> list[float] | None:
		"""
		Get embedding vector for code content.

		Args:
		    content: Code content to embed

		Returns:
		    List of floats representing code embedding or None if unavailable

		"""
		# Skip empty content
		if not content or not content.strip():
			return None

		# Check if embedding model exists
		if self._embedding_model is None:
			logger.warning("Embedding model is None, cannot generate embedding")
			return None

		# Generate embedding with error handling
		try:
			embeddings = self._embedding_model.encode([content], show_progress_bar=False)
			# Check if the result is valid and has the expected structure
			if embeddings is not None and len(embeddings) > 0 and isinstance(embeddings[0], np.ndarray):
				return embeddings[0].tolist()
			logger.warning("Embedding model returned unexpected result type: %s", type(embeddings))
			return None
		except (ValueError, TypeError, RuntimeError, IndexError, AttributeError) as e:
			# Catch a broader range of potential exceptions during encode/toList
			logger.warning("Failed to generate embedding for content snippet: %s", e)
			return None
		except Exception:  # Catch any other unexpected errors
			logger.exception("Unexpected error during embedding generation")
			return None

	def _calculate_semantic_similarity(self, content1: str, content2: str) -> float:
		"""
		Calculate semantic similarity between two code chunks.

		Args:
		    content1: First code content
		    content2: Second code content

		Returns:
		    Similarity score between 0 and 1

		"""
		# Get embeddings
		emb1 = self._get_code_embedding(content1)
		emb2 = self._get_code_embedding(content2)

		if not emb1 or not emb2:
			return 0.0

		# Calculate cosine similarity using utility function
		return calculate_semantic_similarity(emb1, emb2)

	# --- New Helper Methods for Refactoring _enhance_semantic_split ---

	def _parse_file_diff(self, diff_content: str, file_path: str) -> PatchedFile | None:
		"""Parse diff content to find the PatchedFile for a specific file path."""
		if not diff_content:
			logger.warning("Cannot parse empty diff content for %s", file_path)
			return None

		filtered_content = ""  # Initialize to handle unbound case
		try:
			# Filter out the truncation marker lines before parsing
			filtered_content_lines = [
				line for line in diff_content.splitlines() if line.strip() != "... [content truncated] ..."
			]
			filtered_content = "\n".join(filtered_content_lines)

			# Use StringIO as PatchSet expects a file-like object or iterable
			try:
				patch_set = PatchSet(StringIO(filtered_content))
			except UnidiffParseError as e:
				logger.warning("UnidiffParseError for %s: %s", file_path, str(e))
				# Try to extract just the diff for this specific file to avoid parsing the entire diff
				file_diff_content_raw = re.search(
					rf"diff --git a/.*? b/{re.escape(file_path)}\n(.*?)(?=diff --git a/|\Z)",
					diff_content,
					re.DOTALL | re.MULTILINE,
				)
				content_for_chunk = file_diff_content_raw.group(0) if file_diff_content_raw else ""
				if content_for_chunk:
					logger.debug("Extracted raw content for %s after parse error", file_path)
					# Create a manual PatchedFile since we can't parse it properly
					return None
				return None

			matched_file: PatchedFile | None = None
			for patched_file in patch_set:
				# unidiff paths usually start with a/ or b/
				if patched_file.target_file == f"b/{file_path}" or patched_file.path == file_path:
					matched_file = patched_file
					break
			if not matched_file:
				logger.warning("Could not find matching PatchedFile for: %s in unidiff output", file_path)
				return None
			return matched_file
		except UnidiffParseError:
			# Log the specific parse error and the content that caused it (first few lines)
			preview_lines = "\n".join(filtered_content.splitlines()[:10])  # Log first 10 lines
			logger.exception(
				"UnidiffParseError for %s\nContent Preview:\n%s",  # Corrected format string
				file_path,
				preview_lines,
			)
			return None  # Return None on parse error
		except Exception:
			logger.exception("Failed to parse diff content using unidiff for %s", file_path)
			return None

	def _reconstruct_file_diff(self, patched_file: PatchedFile) -> tuple[str, str]:
		"""Reconstruct the diff header and full diff content for a PatchedFile."""
		file_diff_hunks_content = "\n".join(str(hunk) for hunk in patched_file)
		file_header_obj = getattr(patched_file, "patch_info", None)
		file_header = str(file_header_obj) if file_header_obj else ""

		if not file_header.startswith("diff --git") and patched_file.source_file and patched_file.target_file:
			logger.debug("Reconstructing missing diff header for %s", patched_file.path)
			file_header = f"diff --git {patched_file.source_file} {patched_file.target_file}\n"
			if hasattr(patched_file, "index") and patched_file.index:
				file_header += f"index {patched_file.index}\n"
			# Use timestamps if available for more accurate header reconstruction
			source_ts = f"\t{patched_file.source_timestamp}" if patched_file.source_timestamp else ""
			target_ts = f"\t{patched_file.target_timestamp}" if patched_file.target_timestamp else ""
			file_header += f"--- {patched_file.source_file}{source_ts}\n"
			file_header += f"+++ {patched_file.target_file}{target_ts}\n"

		full_file_diff_content = file_header + file_diff_hunks_content
		return file_header, full_file_diff_content

	def _split_large_file_diff(self, patched_file: PatchedFile, file_header: str) -> list[DiffChunk]:
		"""Split a large file's diff by grouping hunks under the size limit."""
		file_path = patched_file.path
		max_chunk_size = self.max_file_size_for_llm  # Use instance config
		logger.info(
			"Splitting large file diff for %s by hunks (limit: %d bytes)",
			file_path,
			max_chunk_size,
		)
		large_file_chunks = []
		current_hunk_group: list[Hunk] = []
		current_group_size = len(file_header)  # Start with header size

		for hunk in patched_file:
			hunk_content_str = str(hunk)
			hunk_size = len(hunk_content_str) + 1  # +1 for newline separator

			# If adding this hunk exceeds the limit (and group isn't empty), finalize the current chunk
			if current_hunk_group and current_group_size + hunk_size > max_chunk_size:
				group_content = file_header + "\n".join(str(h) for h in current_hunk_group)
				description = f"Chunk {len(large_file_chunks) + 1} of large file {file_path}"
				large_file_chunks.append(DiffChunk(files=[file_path], content=group_content, description=description))
				# Start a new chunk with the current hunk
				current_hunk_group = [hunk]
				current_group_size = len(file_header) + hunk_size
			# Edge case: If a single hunk itself is too large, create a chunk just for it
			elif not current_hunk_group and len(file_header) + hunk_size > max_chunk_size:
				logger.warning(
					"Single hunk in %s exceeds size limit (%d bytes). Creating oversized chunk.",
					file_path,
					len(file_header) + hunk_size,
				)
				group_content = file_header + hunk_content_str
				description = f"Chunk {len(large_file_chunks) + 1} (oversized hunk) of large file {file_path}"
				large_file_chunks.append(DiffChunk(files=[file_path], content=group_content, description=description))
				# Reset for next potential chunk (don't carry this huge hunk forward)
				current_hunk_group = []
				current_group_size = len(file_header)
			else:
				# Add hunk to the current group
				current_hunk_group.append(hunk)
				current_group_size += hunk_size

		# Add the last remaining chunk group if any
		if current_hunk_group:
			group_content = file_header + "\n".join(str(h) for h in current_hunk_group)
			description = f"Chunk {len(large_file_chunks) + 1} of large file {file_path}"
			large_file_chunks.append(DiffChunk(files=[file_path], content=group_content, description=description))

		return large_file_chunks

	# --- Refactored Orchestrator Method ---

	def _enhance_semantic_split(self, diff: GitDiff) -> list[DiffChunk]:
		"""
		Enhance the semantic split by using NLP and chunk detection.

		Args:
		    diff: The GitDiff object to split

		Returns:
		    List of enhanced DiffChunk objects

		"""
		if not diff.files:
			return []

		# Special handling for untracked files - avoid unidiff parsing errors
		if diff.is_untracked:
			# Create a basic chunk with only file info for untracked files
			# Use a list comprehension for performance (PERF401)
			return [
				DiffChunk(
					files=[file_path],
					content=diff.content if len(diff.files) == 1 else f"New untracked file: {file_path}",
					description=f"New file: {file_path}",
				)
				for file_path in diff.files
				if self._is_valid_filename(file_path)
			]

		if not diff.files or len(diff.files) != 1:
			logger.error("_enhance_semantic_split called with invalid diff object (files=%s)", diff.files)
			return []

		file_path = diff.files[0]
		extension = Path(file_path).suffix[1:].lower()

		if not diff.content:
			logger.warning("No diff content provided for %s, creating basic chunk.", file_path)
			return [DiffChunk(files=[file_path], content="", description=f"New file: {file_path}")]

		# 1. Parse the diff to get the PatchedFile object
		matched_file = self._parse_file_diff(diff.content, file_path)
		if not matched_file:
			# If parsing failed, return a basic chunk with raw content attempt
			file_diff_content_raw = re.search(
				rf"diff --git a/.*? b/{re.escape(file_path)}\n(.*?)(?=diff --git a/|\Z)",
				diff.content,
				re.DOTALL | re.MULTILINE,
			)
			content_for_chunk = file_diff_content_raw.group(0) if file_diff_content_raw else ""
			return [
				DiffChunk(
					files=[file_path],
					content=content_for_chunk,
					description=f"Changes in {file_path} (parsing failed)",
				)
			]

		# 2. Reconstruct the full diff content for this file
		file_header, full_file_diff_content = self._reconstruct_file_diff(matched_file)

		# 3. Check if the reconstructed diff is too large
		if len(full_file_diff_content) > self.max_file_size_for_llm:
			return self._split_large_file_diff(matched_file, file_header)

		# 4. Try splitting by semantic patterns (if applicable)
		patterns = get_language_specific_patterns(extension)
		if patterns:
			logger.debug("Attempting semantic pattern splitting for %s", file_path)
			pattern_chunks = self._split_by_semantic_patterns(matched_file, patterns)
			if pattern_chunks:
				return pattern_chunks
			logger.debug("Pattern splitting yielded no chunks for %s, falling back.", file_path)

		# 5. Fallback: Split by individual hunks
		logger.debug("Falling back to hunk splitting for %s", file_path)
		hunk_chunks = []
		for hunk in matched_file:
			hunk_content = str(hunk)
			hunk_chunks.append(
				DiffChunk(
					files=[file_path],
					content=file_header + hunk_content,  # Combine header + hunk
					description=f"Hunk in {file_path} starting near line {hunk.target_start}",
				)
			)

		# If no hunks were found at all, return the single reconstructed chunk
		if not hunk_chunks:
			logger.warning("No hunks detected for %s after parsing, returning full diff.", file_path)
			return [
				DiffChunk(
					files=[file_path],
					content=full_file_diff_content,
					description=f"Changes in {file_path} (no hunks detected)",
				)
			]

		return hunk_chunks

	# --- Existing Helper Methods (Potentially need review/updates) ---

	def _group_by_content_similarity(
		self,
		chunks: list[DiffChunk],
		result_chunks: list[DiffChunk],
		similarity_threshold: float | None = None,
	) -> None:
		"""
		Group chunks by content similarity.

		Args:
		    chunks: List of chunks to process
		    result_chunks: List to append grouped chunks to (modified in place)
		    similarity_threshold: Optional custom threshold to override default

		"""
		if not chunks:
			return

		# Check if model is available
		if self._embedding_model is None:
			logger.debug("Embedding model not available, using fallback grouping strategy")
			# If model is unavailable, try to group by file path patterns
			grouped_paths: dict[str, list[DiffChunk]] = {}

			# Group by common path prefixes
			for chunk in chunks:
				if not chunk.files:
					result_chunks.append(chunk)
					continue

				file_path = chunk.files[0]
				# Get directory or file prefix as the grouping key
				if "/" in file_path:
					# Use directory as key
					key = file_path.rsplit("/", 1)[0]
				else:
					# Use file prefix (before extension) as key
					key = file_path.split(".", 1)[0] if "." in file_path else file_path

				if key not in grouped_paths:
					grouped_paths[key] = []
				grouped_paths[key].append(chunk)

			# Create chunks from each group
			for related_chunks in grouped_paths.values():
				self._create_semantic_chunk(related_chunks, result_chunks)
			return

		processed_indices = set()
		threshold = similarity_threshold if similarity_threshold is not None else self.similarity_threshold

		# For each chunk, find similar chunks and group them
		for i, chunk in enumerate(chunks):
			if i in processed_indices:
				continue

			related_chunks = [chunk]
			processed_indices.add(i)

			# Find similar chunks
			for j, other_chunk in enumerate(chunks):
				if i == j or j in processed_indices:
					continue

				# Calculate similarity between chunks
				similarity = self._calculate_semantic_similarity(chunk.content, other_chunk.content)

				if similarity >= threshold:
					related_chunks.append(other_chunk)
					processed_indices.add(j)

			# Create a semantic chunk from related chunks
			if related_chunks:
				self._create_semantic_chunk(related_chunks, result_chunks)

	def _group_related_files(
		self,
		file_chunks: list[DiffChunk],
		processed_files: set[str],
		semantic_chunks: list[DiffChunk],
	) -> None:
		"""
		Group related files into semantic chunks.

		Args:
		    file_chunks: List of file-based chunks
		    processed_files: Set of already processed files (modified in place)
		    semantic_chunks: List of semantic chunks (modified in place)

		"""
		if not file_chunks:
			return

		# Group clearly related files
		for i, chunk in enumerate(file_chunks):
			if not chunk.files or chunk.files[0] in processed_files:
				continue

			related_chunks = [chunk]
			processed_files.add(chunk.files[0])

			# Find related files
			for j, other_chunk in enumerate(file_chunks):
				if i == j or not other_chunk.files or other_chunk.files[0] in processed_files:
					continue

				if are_files_related(chunk.files[0], other_chunk.files[0], self.related_file_patterns):
					related_chunks.append(other_chunk)
					processed_files.add(other_chunk.files[0])

			# Create a semantic chunk from related files
			if related_chunks:
				self._create_semantic_chunk(related_chunks, semantic_chunks)

	def _create_semantic_chunk(
		self,
		related_chunks: list[DiffChunk],
		semantic_chunks: list[DiffChunk],
	) -> None:
		"""
		Create a semantic chunk from related file chunks.

		Args:
		    related_chunks: List of related file chunks
		    semantic_chunks: List of semantic chunks to append to (modified in place)

		"""
		if not related_chunks:
			return

		all_files = []
		combined_content = []

		for rc in related_chunks:
			all_files.extend(rc.files)
			combined_content.append(rc.content)

		# Determine the appropriate commit type based on the files
		commit_type = determine_commit_type(all_files)

		# Create description based on file count
		description = create_chunk_description(commit_type, all_files)

		# Join the content from all related chunks
		content = "\n\n".join(combined_content)

		semantic_chunks.append(
			DiffChunk(
				files=all_files,
				content=content,
				description=description,
			)
		)

	def _should_merge_chunks(self, chunk1: DiffChunk, chunk2: DiffChunk) -> bool:
		"""Determine if two chunks should be merged."""
		# Condition 1: Same single file
		same_file = len(chunk1.files) == 1 and chunk1.files == chunk2.files

		# Condition 2: Related single files
		related_files = (
			len(chunk1.files) == 1
			and len(chunk2.files) == 1
			and are_files_related(chunk1.files[0], chunk2.files[0], self.related_file_patterns)
		)

		# Return True if either condition is met
		return same_file or related_files

	def _consolidate_small_chunks(self, initial_chunks: list[DiffChunk]) -> list[DiffChunk]:
		"""
		Merge small or related chunks together.

		First, consolidates chunks originating from the same file.
		Then, consolidates remaining single-file chunks by directory.

		Args:
		    initial_chunks: List of diff chunks to consolidate

		Returns:
		    Consolidated list of chunks

		"""
		# Use instance variable for threshold
		if len(initial_chunks) < self.min_chunks_for_consolidation:
			return initial_chunks

		# Consolidate small chunks for the same file or related files
		consolidated_chunks = []
		processed_indices = set()

		for i, chunk1 in enumerate(initial_chunks):
			if i in processed_indices:
				continue

			merged_chunk = chunk1
			processed_indices.add(i)

			# Check subsequent chunks for merging
			for j in range(i + 1, len(initial_chunks)):
				if j in processed_indices:
					continue

				chunk2 = initial_chunks[j]

				# Check if chunks should be merged (same file or related)
				if self._should_merge_chunks(merged_chunk, chunk2):
					# Combine files if merging related chunks, not just same file chunks
					new_files = merged_chunk.files
					if (
						len(merged_chunk.files) == 1
						and len(chunk2.files) == 1
						and merged_chunk.files[0] != chunk2.files[0]
					):
						new_files = sorted(set(merged_chunk.files + chunk2.files))

					# Merge content and potentially other attributes
					# Ensure a newline between merged content if needed
					separator = "\n" if merged_chunk.content and chunk2.content else ""
					merged_chunk = dataclasses.replace(
						merged_chunk,
						files=new_files,
						content=merged_chunk.content + separator + chunk2.content,
						description=merged_chunk.description,  # Keep first description
					)
					processed_indices.add(j)

			consolidated_chunks.append(merged_chunk)

		return consolidated_chunks

	def _split_by_semantic_patterns(self, patched_file: PatchedFile, patterns: list[str]) -> list[DiffChunk]:
		"""
		Split a PatchedFile's content by grouping hunks based on semantic patterns.

		This method groups consecutive hunks together until a hunk is encountered
		that contains an added line matching one of the semantic boundary patterns.
		It does *not* split within a single hunk, only between hunks where a boundary
		is detected in the *first* line of the subsequent hunk group.

		Args:
		    patched_file: The PatchedFile object from unidiff.
		    patterns: List of regex pattern strings to match as boundaries.

		Returns:
		    List of DiffChunk objects, potentially splitting the file into multiple chunks.

		"""
		compiled_patterns = [re.compile(p) for p in patterns]
		file_path = patched_file.path  # Or target_file? Need consistency

		final_chunks_data: list[list[Hunk]] = []
		current_semantic_chunk_hunks: list[Hunk] = []

		# Get header info once using the reconstruction helper
		file_header, _ = self._reconstruct_file_diff(patched_file)

		for hunk in patched_file:
			hunk_has_boundary = False
			for line in hunk:
				if line.is_added and any(pattern.match(line.value) for pattern in compiled_patterns):
					hunk_has_boundary = True
					break  # Found a boundary in this hunk

			# Start a new semantic chunk if the current hunk has a boundary
			# and we already have hunks accumulated.
			if hunk_has_boundary and current_semantic_chunk_hunks:
				final_chunks_data.append(current_semantic_chunk_hunks)
				current_semantic_chunk_hunks = [hunk]  # Start new chunk with this hunk
			else:
				# Append the current hunk to the ongoing semantic chunk
				current_semantic_chunk_hunks.append(hunk)

		# Add the last accumulated semantic chunk
		if current_semantic_chunk_hunks:
			final_chunks_data.append(current_semantic_chunk_hunks)

		# Convert grouped hunks into DiffChunk objects
		result_chunks: list[DiffChunk] = []
		for i, hunk_group in enumerate(final_chunks_data):
			if not hunk_group:
				continue
			# Combine content of all hunks in the group
			group_content = "\n".join(str(h) for h in hunk_group)
			# Generate description (could be more sophisticated)
			description = f"Semantic section {i + 1} in {file_path}"
			result_chunks.append(
				DiffChunk(
					files=[file_path],
					content=file_header + group_content,  # Combine header + hunks
					description=description,
				)
			)

		logger.debug("Split %s into %d chunks based on semantic patterns", file_path, len(result_chunks))
		return result_chunks

	@staticmethod
	def _is_valid_filename(filename: str) -> bool:
		"""Check if the filename is valid (not a pattern or template)."""
		if not filename:
			return False
		invalid_chars = ["*", "+", "{", "}", "\\"]
		return not (any(char in filename for char in invalid_chars) or filename.startswith('"'))

__init__

__init__(
	embedding_model: EmbeddingModel | None = None,
	code_extensions: set[str] | None = None,
	related_file_patterns: list[tuple[Pattern, Pattern]]
	| None = None,
	similarity_threshold: float = 0.4,
	directory_similarity_threshold: float = 0.3,
	min_chunks_for_consolidation: int = 2,
	max_chunks_before_consolidation: int = 20,
	max_file_size_for_llm: int | None = None,
) -> None

Initialize the SemanticSplitStrategy.

Parameters:

Name	Type	Description	Default
embedding_model	EmbeddingModel | None	Optional embedding model instance	None
code_extensions	set[str] | None	Optional set of code file extensions. Defaults to config.	None
related_file_patterns	list[tuple[Pattern, Pattern]] | None	Optional list of related file patterns	None
similarity_threshold	float	Threshold for grouping by content similarity.	0.4
directory_similarity_threshold	float	Threshold for directory similarity.	0.3
min_chunks_for_consolidation	int	Min chunks to trigger consolidation.	2
max_chunks_before_consolidation	int	Max chunks allowed before forced consolidation.	20
max_file_size_for_llm	int | None	Max file size for LLM processing.	None

Source code in src/codemap/git/diff_splitter/strategies.py

def __init__(
	self,
	embedding_model: EmbeddingModel | None = None,
	code_extensions: set[str] | None = None,
	related_file_patterns: list[tuple[Pattern, Pattern]] | None = None,
	similarity_threshold: float = 0.4,
	directory_similarity_threshold: float = 0.3,
	min_chunks_for_consolidation: int = 2,
	max_chunks_before_consolidation: int = 20,
	max_file_size_for_llm: int | None = None,
) -> None:
	"""
	Initialize the SemanticSplitStrategy.

	Args:
	    embedding_model: Optional embedding model instance
	    code_extensions: Optional set of code file extensions. Defaults to config.
	    related_file_patterns: Optional list of related file patterns
	    similarity_threshold: Threshold for grouping by content similarity.
	    directory_similarity_threshold: Threshold for directory similarity.
	    min_chunks_for_consolidation: Min chunks to trigger consolidation.
	    max_chunks_before_consolidation: Max chunks allowed before forced consolidation.
	    max_file_size_for_llm: Max file size for LLM processing.

	"""
	super().__init__(embedding_model)
	# Store thresholds and settings
	self.similarity_threshold = similarity_threshold
	self.directory_similarity_threshold = directory_similarity_threshold
	self.min_chunks_for_consolidation = min_chunks_for_consolidation
	self.max_chunks_before_consolidation = max_chunks_before_consolidation
	# Use default from config if not provided
	self.max_file_size_for_llm = (
		max_file_size_for_llm
		if max_file_size_for_llm is not None
		else DEFAULT_CONFIG["commit"]["diff_splitter"]["max_file_size_for_llm"]
	)

	# Set up file extensions, defaulting to config if None is passed
	self.code_extensions = (
		code_extensions
		if code_extensions is not None
		else set(DEFAULT_CONFIG["commit"]["diff_splitter"]["default_code_extensions"])
	)
	# Initialize patterns for related files
	self.related_file_patterns = related_file_patterns or self._initialize_related_file_patterns()

similarity_threshold instance-attribute

similarity_threshold = similarity_threshold

directory_similarity_threshold instance-attribute

directory_similarity_threshold = (
	directory_similarity_threshold
)

min_chunks_for_consolidation instance-attribute

min_chunks_for_consolidation = min_chunks_for_consolidation

max_chunks_before_consolidation instance-attribute

max_chunks_before_consolidation = (
	max_chunks_before_consolidation
)

max_file_size_for_llm instance-attribute

max_file_size_for_llm = (
	max_file_size_for_llm
	if max_file_size_for_llm is not None
	else DEFAULT_CONFIG["commit"]["diff_splitter"][
		"max_file_size_for_llm"
	]
)

code_extensions instance-attribute

code_extensions = (
	code_extensions
	if code_extensions is not None
	else set(
		DEFAULT_CONFIG["commit"]["diff_splitter"][
			"default_code_extensions"
		]
	)
)

related_file_patterns instance-attribute

related_file_patterns = (
	related_file_patterns
	or _initialize_related_file_patterns()
)

split

split(diff: GitDiff) -> list[DiffChunk]

Split a diff into chunks based on semantic relationships.

Parameters:

Name	Type	Description	Default
diff	GitDiff	GitDiff object to split	required

Returns:

Type	Description
list[DiffChunk]	List of DiffChunk objects based on semantic analysis

Source code in src/codemap/git/diff_splitter/strategies.py

def split(self, diff: GitDiff) -> list[DiffChunk]:
	"""
	Split a diff into chunks based on semantic relationships.

	Args:
	    diff: GitDiff object to split

	Returns:
	    List of DiffChunk objects based on semantic analysis

	"""
	if not diff.files:
		logger.debug("No files to process")
		return []

	# Validate embedding model is available
	self._validate_embedding_model()

	# Handle files in manageable groups
	if len(diff.files) > MAX_FILES_PER_GROUP:
		logger.info("Processing large number of files (%d) in smaller groups", len(diff.files))

		# Group files by directory to increase likelihood of related files being processed together
		files_by_dir = {}
		for file in diff.files:
			dir_path = str(Path(file).parent)
			if dir_path not in files_by_dir:
				files_by_dir[dir_path] = []
			files_by_dir[dir_path].append(file)

		# Process each directory group separately, keeping chunks under 5 files
		all_chunks = []
		# Iterate directly over the file lists since the directory path isn't used here
		for files in files_by_dir.values():
			# Process files in this directory in batches of 3-5
			for i in range(0, len(files), 3):
				batch = files[i : i + 3]
				# Create a new GitDiff for the batch, ensuring content is passed
				batch_diff = GitDiff(
					files=batch,
					content=diff.content,  # Pass the original full diff content
					is_staged=diff.is_staged,
				)
				all_chunks.extend(self._process_group(batch_diff))

		return all_chunks

	# For smaller groups, process normally
	return self._process_group(diff)

calculate_semantic_similarity

calculate_semantic_similarity(
	emb1: list[float], emb2: list[float]
) -> float

Calculate semantic similarity (cosine similarity) between two embedding vectors.

Parameters:

Name	Type	Description	Default
emb1	list[float]	First embedding vector	required
emb2	list[float]	Second embedding vector	required

Returns:

Type	Description
float	Similarity score between 0 and 1

Source code in src/codemap/git/diff_splitter/utils.py

def calculate_semantic_similarity(emb1: list[float], emb2: list[float]) -> float:
	"""
	Calculate semantic similarity (cosine similarity) between two embedding vectors.

	Args:
	    emb1: First embedding vector
	    emb2: Second embedding vector

	Returns:
	    Similarity score between 0 and 1

	"""
	if not emb1 or not emb2:
		return 0.0

	try:
		# Convert to numpy arrays
		vec1 = np.array(emb1, dtype=np.float64)
		vec2 = np.array(emb2, dtype=np.float64)

		# Calculate cosine similarity
		dot_product = np.dot(vec1, vec2)
		norm1 = np.linalg.norm(vec1)
		norm2 = np.linalg.norm(vec2)

		if norm1 <= EPSILON or norm2 <= EPSILON:
			return 0.0

		similarity = float(dot_product / (norm1 * norm2))

		# Handle potential numeric issues
		if not np.isfinite(similarity):
			return 0.0

		return max(0.0, min(1.0, similarity))  # Clamp to [0, 1]

	except (ValueError, TypeError, ArithmeticError, OverflowError):
		logger.warning("Failed to calculate similarity")
		return 0.0

create_chunk_description

create_chunk_description(
	commit_type: str, files: list[str]
) -> str

Create a meaningful description for a chunk.

Parameters:

Name	Type	Description	Default
commit_type	str	Type of commit (e.g., "feat", "fix")	required
files	list[str]	List of file paths	required

Returns:

Type	Description
str	Description string

Source code in src/codemap/git/diff_splitter/utils.py

def create_chunk_description(commit_type: str, files: list[str]) -> str:
	"""
	Create a meaningful description for a chunk.

	Args:
	    commit_type: Type of commit (e.g., "feat", "fix")
	    files: List of file paths

	Returns:
	    Description string

	"""
	if len(files) == 1:
		return f"{commit_type}: update {files[0]}"

	# Try to find a common directory using Path for better cross-platform compatibility
	try:
		common_dir = Path(os.path.commonpath(files))
		if str(common_dir) not in (".", ""):
			return f"{commit_type}: update files in {common_dir}"
	except ValueError:
		# commonpath raises ValueError if files are on different drives
		pass

	return f"{commit_type}: update {len(files)} related files"

determine_commit_type

determine_commit_type(files: list[str]) -> str

Determine the appropriate commit type based on the files.

Parameters:

Name	Type	Description	Default
files	list[str]	List of file paths	required

Returns:

Type	Description
str	Commit type string (e.g., "feat", "fix", "test", "docs", "chore")

Source code in src/codemap/git/diff_splitter/utils.py

def determine_commit_type(files: list[str]) -> str:
	"""
	Determine the appropriate commit type based on the files.

	Args:
	    files: List of file paths

	Returns:
	    Commit type string (e.g., "feat", "fix", "test", "docs", "chore")

	"""
	# Check for test files
	if any(f.startswith("tests/") or "_test." in f or "test_" in f for f in files):
		return "test"

	# Check for documentation files
	if any(f.startswith("docs/") or f.endswith(".md") for f in files):
		return "docs"

	# Check for configuration files
	if any(f.endswith((".json", ".yml", ".yaml", ".toml", ".ini", ".cfg")) for f in files):
		return "chore"

	# Default to "chore" for general updates
	return "chore"

filter_valid_files

filter_valid_files(
	files: list[str], is_test_environment: bool = False
) -> tuple[list[str], list[str]]

Filter invalid filenames and files based on existence and Git tracking.

Parameters:

Name	Type	Description	Default
files	list[str]	List of file paths to filter	required
is_test_environment	bool	Whether running in a test environment	False

Returns:

Type	Description
tuple[list[str], list[str]]	Tuple of (valid_files, empty_list) - The second element is always an empty list now.

Source code in src/codemap/git/diff_splitter/utils.py

def filter_valid_files(files: list[str], is_test_environment: bool = False) -> tuple[list[str], list[str]]:
	"""
	Filter invalid filenames and files based on existence and Git tracking.

	Args:
	    files: List of file paths to filter
	    is_test_environment: Whether running in a test environment

	Returns:
	    Tuple of (valid_files, empty_list) - The second element is always an empty list now.

	"""
	if not files:
		return [], []

	valid_files_intermediate = []
	# Keep track of files filtered due to large size if needed elsewhere,
	# but don't remove them from processing yet.

	for file in files:
		# Skip files that look like patterns or templates
		if any(char in file for char in ["*", "+", "{", "}", "\\"]) or file.startswith('"'):
			logger.warning("Skipping invalid filename in diff processing: %s", file)
			continue
		valid_files_intermediate.append(file)

	# --- File Existence and Git Tracking Checks ---
	valid_files = []  # Reset valid_files to populate after existence checks

	# Skip file existence checks in test environments
	if is_test_environment:
		logger.debug("In test environment - skipping file existence checks for %d files", len(valid_files_intermediate))
		# In test env, assume all intermediate files are valid regarding existence/tracking
		valid_files = valid_files_intermediate
	else:
		# Get deleted files
		deleted_unstaged_files, deleted_staged_files = get_deleted_tracked_files()

		# Check if files exist in the repository (tracked by git) or filesystem
		original_count = len(valid_files_intermediate)
		try:
			tracked_files_output = run_git_command(["git", "ls-files"])
			tracked_files = set(tracked_files_output.splitlines())

			# Keep files that either:
			# 1. Exist in filesystem
			# 2. Are tracked by git
			# 3. Are known deleted files from git status
			# 4. Are already staged deletions
			filtered_files = []
			for file in valid_files_intermediate:
				try:
					path_exists = Path(file).exists()
				except OSError as e:
					logger.warning("OS error checking existence for %s: %s. Skipping file.", file, e)
					continue
				except Exception:
					logger.exception("Unexpected error checking existence for %s. Skipping file.", file)
					continue

				if (
					path_exists
					or file in tracked_files
					or file in deleted_unstaged_files
					or file in deleted_staged_files
				):
					filtered_files.append(file)
				else:
					logger.warning("Skipping non-existent/untracked/not-deleted file in diff: %s", file)

			valid_files = filtered_files
			if len(valid_files) < original_count:
				logger.warning(
					"Filtered out %d files that don't exist or aren't tracked/deleted",
					original_count - len(valid_files),
				)
		except GitError as e:  # Catch GitError from run_git_command
			logger.warning("Failed to get tracked files from git: %s. Filtering based on existence only.", e)
			# If we can't check git tracked files, filter by filesystem existence and git status
			filtered_files_fallback = []
			for file in valid_files_intermediate:
				try:
					path_exists = Path(file).exists()
				except OSError as e:
					logger.warning("OS error checking existence for %s: %s. Skipping file.", file, e)
					continue
				except Exception:
					logger.exception("Unexpected error checking existence for %s. Skipping file.", file)
					continue

				if path_exists or file in deleted_unstaged_files or file in deleted_staged_files:
					filtered_files_fallback.append(file)
				else:
					logger.warning("Skipping non-existent/not-deleted file in diff (git check failed): %s", file)

			valid_files = filtered_files_fallback  # Replace valid_files with the fallback list
			if len(valid_files) < original_count:
				# Adjust log message if git check failed
				logger.warning(
					"Filtered out %d files that don't exist (git check failed)",
					original_count - len(valid_files),
				)
		except Exception:  # Catch any other unexpected errors during the initial try block
			logger.exception("Unexpected error during file filtering. Proceeding with potentially incorrect list.")
			# If a catastrophic error occurs, proceed with the intermediate list
			valid_files = valid_files_intermediate

	# Return only the list of valid files. The concept of 'filtered_large_files' is removed.
	# Size checking will now happen within the splitting strategy.
	return valid_files, []  # Return empty list for the second element now.

get_language_specific_patterns

get_language_specific_patterns(language: str) -> list[str]

Get language-specific regex patterns for code structure.

Parameters:

Name	Type	Description	Default
language	str	Programming language identifier	required

Returns:

Type	Description
list[str]	A list of regex patterns for the language, or empty list if not supported

Source code in src/codemap/git/diff_splitter/utils.py

def get_language_specific_patterns(language: str) -> list[str]:
	"""
	Get language-specific regex patterns for code structure.

	Args:
	    language: Programming language identifier

	Returns:
	    A list of regex patterns for the language, or empty list if not supported

	"""
	# Define pattern strings (used for semantic boundary detection)
	pattern_strings = {
		"py": [
			r"^import\s+.*",  # Import statements
			r"^from\s+.*",  # From imports
			r"^class\s+\w+",  # Class definitions
			r"^def\s+\w+",  # Function definitions
			r"^if\s+__name__\s*==\s*['\"]__main__['\"]",  # Main block
		],
		"js": [
			r"^import\s+.*",  # ES6 imports
			r"^const\s+\w+\s*=\s*require",  # CommonJS imports
			r"^function\s+\w+",  # Function declarations
			r"^const\s+\w+\s*=\s*function",  # Function expressions
			r"^class\s+\w+",  # Class declarations
			r"^export\s+",  # Exports
		],
		"ts": [
			r"^import\s+.*",  # Imports
			r"^export\s+",  # Exports
			r"^interface\s+",  # Interfaces
			r"^type\s+",  # Type definitions
			r"^class\s+",  # Classes
			r"^function\s+",  # Functions
		],
		"jsx": [
			r"^import\s+.*",  # ES6 imports
			r"^const\s+\w+\s*=\s*require",  # CommonJS imports
			r"^function\s+\w+",  # Function declarations
			r"^const\s+\w+\s*=\s*function",  # Function expressions
			r"^class\s+\w+",  # Class declarations
			r"^export\s+",  # Exports
		],
		"tsx": [
			r"^import\s+.*",  # Imports
			r"^export\s+",  # Exports
			r"^interface\s+",  # Interfaces
			r"^type\s+",  # Type definitions
			r"^class\s+",  # Classes
			r"^function\s+",  # Functions
		],
		"java": [
			r"^import\s+.*",  # Import statements
			r"^public\s+class",  # Public class
			r"^private\s+class",  # Private class
			r"^(public|private|protected)(\s+static)?\s+\w+\s+\w+\(",  # Methods
		],
		"go": [
			r"^import\s+",  # Import statements
			r"^func\s+",  # Function definitions
			r"^type\s+\w+\s+struct",  # Struct definitions
		],
		"rb": [
			r"^require\s+",  # Requires
			r"^class\s+",  # Class definitions
			r"^def\s+",  # Method definitions
			r"^module\s+",  # Module definitions
		],
		"php": [
			r"^namespace\s+",  # Namespace declarations
			r"^use\s+",  # Use statements
			r"^class\s+",  # Class definitions
			r"^(public|private|protected)\s+function",  # Methods
		],
		"cs": [
			r"^using\s+",  # Using directives
			r"^namespace\s+",  # Namespace declarations
			r"^(public|private|protected|internal)\s+class",  # Classes
			r"^(public|private|protected|internal)(\s+static)?\s+\w+\s+\w+\(",  # Methods
		],
		"kt": [
			r"^import\s+.*",  # Import statements
			r"^class\s+\w+",  # Class definitions
			r"^fun\s+\w+",  # Function definitions
			r"^val\s+\w+",  # Val declarations
			r"^var\s+\w+",  # Var declarations
		],
		"scala": [
			r"^import\s+.*",  # Import statements
			r"^class\s+\w+",  # Class definitions
			r"^object\s+\w+",  # Object definitions
			r"^def\s+\w+",  # Method definitions
			r"^val\s+\w+",  # Val declarations
			r"^var\s+\w+",  # Var declarations
		],
	}

	# Return pattern strings for the language or empty list if not supported
	return pattern_strings.get(language, [])

is_test_environment

is_test_environment() -> bool

Check if the code is running in a test environment.

Returns:

Type	Description
bool	True if in a test environment, False otherwise

Source code in src/codemap/git/diff_splitter/utils.py

def is_test_environment() -> bool:
	"""
	Check if the code is running in a test environment.

	Returns:
	    True if in a test environment, False otherwise

	"""
	# Check multiple environment indicators for tests
	return "PYTEST_CURRENT_TEST" in os.environ or "pytest" in sys.modules or os.environ.get("TESTING") == "1"

schemas

Schema definitions for diff splitting.

DiffChunk dataclass

Represents a logical chunk of changes.

Source code in src/codemap/git/diff_splitter/schemas.py

@dataclass
class DiffChunk:
	"""Represents a logical chunk of changes."""

	files: list[str]
	content: str
	description: str | None = None
	is_llm_generated: bool = False
	filtered_files: list[str] | None = None

	def __post_init__(self) -> None:
		"""Initialize default values."""
		if self.filtered_files is None:
			self.filtered_files = []

	def __hash__(self) -> int:
		"""
		Make DiffChunk hashable by using the object's id.

		Returns:
		        Hash value based on the object's id

		"""
		return hash(id(self))

	def __eq__(self, other: object) -> bool:
		"""
		Compare DiffChunk objects for equality.

		Args:
		        other: Another object to compare with

		Returns:
		        True if the objects are the same instance, False otherwise

		"""
		if not isinstance(other, DiffChunk):
			return False
		return id(self) == id(other)

__init__

__init__(
	files: list[str],
	content: str,
	description: str | None = None,
	is_llm_generated: bool = False,
	filtered_files: list[str] | None = None,
) -> None

files instance-attribute

files: list[str]

content instance-attribute

content: str

description class-attribute instance-attribute

description: str | None = None

is_llm_generated class-attribute instance-attribute

is_llm_generated: bool = False

filtered_files class-attribute instance-attribute

filtered_files: list[str] | None = None

__post_init__

__post_init__() -> None

Initialize default values.

Source code in src/codemap/git/diff_splitter/schemas.py

def __post_init__(self) -> None:
	"""Initialize default values."""
	if self.filtered_files is None:
		self.filtered_files = []

__hash__

__hash__() -> int

Make DiffChunk hashable by using the object's id.

Returns:

Type	Description
int	Hash value based on the object's id

Source code in src/codemap/git/diff_splitter/schemas.py

def __hash__(self) -> int:
	"""
	Make DiffChunk hashable by using the object's id.

	Returns:
	        Hash value based on the object's id

	"""
	return hash(id(self))

__eq__

__eq__(other: object) -> bool

Compare DiffChunk objects for equality.

Parameters:

Name	Type	Description	Default
other	object	Another object to compare with	required

Returns:

Type	Description
bool	True if the objects are the same instance, False otherwise

Source code in src/codemap/git/diff_splitter/schemas.py

def __eq__(self, other: object) -> bool:
	"""
	Compare DiffChunk objects for equality.

	Args:
	        other: Another object to compare with

	Returns:
	        True if the objects are the same instance, False otherwise

	"""
	if not isinstance(other, DiffChunk):
		return False
	return id(self) == id(other)

DiffChunkData dataclass

Dictionary-based representation of a DiffChunk for serialization.

Source code in src/codemap/git/diff_splitter/schemas.py

@dataclass
class DiffChunkData:
	"""Dictionary-based representation of a DiffChunk for serialization."""

	files: list[str]
	content: str
	description: str | None = None
	is_llm_generated: bool = False
	filtered_files: list[str] | None = None

	@classmethod
	def from_chunk(cls, chunk: DiffChunk) -> "DiffChunkData":
		"""Create a DiffChunkData from a DiffChunk."""
		return cls(
			files=chunk.files,
			content=chunk.content,
			description=chunk.description,
			is_llm_generated=chunk.is_llm_generated,
			filtered_files=chunk.filtered_files,
		)

	def to_chunk(self) -> DiffChunk:
		"""Convert DiffChunkData to a DiffChunk."""
		return DiffChunk(
			files=self.files,
			content=self.content,
			description=self.description,
			is_llm_generated=self.is_llm_generated,
			filtered_files=self.filtered_files,
		)

	def to_dict(self) -> dict[str, Any]:
		"""Convert to a dictionary."""
		return {
			"files": self.files,
			"content": self.content,
			"description": self.description,
			"is_llm_generated": self.is_llm_generated,
			"filtered_files": self.filtered_files,
		}

__init__

__init__(
	files: list[str],
	content: str,
	description: str | None = None,
	is_llm_generated: bool = False,
	filtered_files: list[str] | None = None,
) -> None

files instance-attribute

files: list[str]

content instance-attribute

content: str

description class-attribute instance-attribute

description: str | None = None

is_llm_generated class-attribute instance-attribute

is_llm_generated: bool = False

filtered_files class-attribute instance-attribute

filtered_files: list[str] | None = None

from_chunk classmethod

from_chunk(chunk: DiffChunk) -> DiffChunkData

Create a DiffChunkData from a DiffChunk.

Source code in src/codemap/git/diff_splitter/schemas.py

@classmethod
def from_chunk(cls, chunk: DiffChunk) -> "DiffChunkData":
	"""Create a DiffChunkData from a DiffChunk."""
	return cls(
		files=chunk.files,
		content=chunk.content,
		description=chunk.description,
		is_llm_generated=chunk.is_llm_generated,
		filtered_files=chunk.filtered_files,
	)

to_chunk

to_chunk() -> DiffChunk

Convert DiffChunkData to a DiffChunk.

Source code in src/codemap/git/diff_splitter/schemas.py

def to_chunk(self) -> DiffChunk:
	"""Convert DiffChunkData to a DiffChunk."""
	return DiffChunk(
		files=self.files,
		content=self.content,
		description=self.description,
		is_llm_generated=self.is_llm_generated,
		filtered_files=self.filtered_files,
	)

to_dict

to_dict() -> dict[str, Any]

Convert to a dictionary.

Source code in src/codemap/git/diff_splitter/schemas.py

def to_dict(self) -> dict[str, Any]:
	"""Convert to a dictionary."""
	return {
		"files": self.files,
		"content": self.content,
		"description": self.description,
		"is_llm_generated": self.is_llm_generated,
		"filtered_files": self.filtered_files,
	}

utils

Utility functions for diff splitting.

get_language_specific_patterns

get_language_specific_patterns(language: str) -> list[str]

Get language-specific regex patterns for code structure.

Parameters:

Name	Type	Description	Default
language	str	Programming language identifier	required

Returns:

Type	Description
list[str]	A list of regex patterns for the language, or empty list if not supported

Source code in src/codemap/git/diff_splitter/utils.py

def get_language_specific_patterns(language: str) -> list[str]:
	"""
	Get language-specific regex patterns for code structure.

	Args:
	    language: Programming language identifier

	Returns:
	    A list of regex patterns for the language, or empty list if not supported

	"""
	# Define pattern strings (used for semantic boundary detection)
	pattern_strings = {
		"py": [
			r"^import\s+.*",  # Import statements
			r"^from\s+.*",  # From imports
			r"^class\s+\w+",  # Class definitions
			r"^def\s+\w+",  # Function definitions
			r"^if\s+__name__\s*==\s*['\"]__main__['\"]",  # Main block
		],
		"js": [
			r"^import\s+.*",  # ES6 imports
			r"^const\s+\w+\s*=\s*require",  # CommonJS imports
			r"^function\s+\w+",  # Function declarations
			r"^const\s+\w+\s*=\s*function",  # Function expressions
			r"^class\s+\w+",  # Class declarations
			r"^export\s+",  # Exports
		],
		"ts": [
			r"^import\s+.*",  # Imports
			r"^export\s+",  # Exports
			r"^interface\s+",  # Interfaces
			r"^type\s+",  # Type definitions
			r"^class\s+",  # Classes
			r"^function\s+",  # Functions
		],
		"jsx": [
			r"^import\s+.*",  # ES6 imports
			r"^const\s+\w+\s*=\s*require",  # CommonJS imports
			r"^function\s+\w+",  # Function declarations
			r"^const\s+\w+\s*=\s*function",  # Function expressions
			r"^class\s+\w+",  # Class declarations
			r"^export\s+",  # Exports
		],
		"tsx": [
			r"^import\s+.*",  # Imports
			r"^export\s+",  # Exports
			r"^interface\s+",  # Interfaces
			r"^type\s+",  # Type definitions
			r"^class\s+",  # Classes
			r"^function\s+",  # Functions
		],
		"java": [
			r"^import\s+.*",  # Import statements
			r"^public\s+class",  # Public class
			r"^private\s+class",  # Private class
			r"^(public|private|protected)(\s+static)?\s+\w+\s+\w+\(",  # Methods
		],
		"go": [
			r"^import\s+",  # Import statements
			r"^func\s+",  # Function definitions
			r"^type\s+\w+\s+struct",  # Struct definitions
		],
		"rb": [
			r"^require\s+",  # Requires
			r"^class\s+",  # Class definitions
			r"^def\s+",  # Method definitions
			r"^module\s+",  # Module definitions
		],
		"php": [
			r"^namespace\s+",  # Namespace declarations
			r"^use\s+",  # Use statements
			r"^class\s+",  # Class definitions
			r"^(public|private|protected)\s+function",  # Methods
		],
		"cs": [
			r"^using\s+",  # Using directives
			r"^namespace\s+",  # Namespace declarations
			r"^(public|private|protected|internal)\s+class",  # Classes
			r"^(public|private|protected|internal)(\s+static)?\s+\w+\s+\w+\(",  # Methods
		],
		"kt": [
			r"^import\s+.*",  # Import statements
			r"^class\s+\w+",  # Class definitions
			r"^fun\s+\w+",  # Function definitions
			r"^val\s+\w+",  # Val declarations
			r"^var\s+\w+",  # Var declarations
		],
		"scala": [
			r"^import\s+.*",  # Import statements
			r"^class\s+\w+",  # Class definitions
			r"^object\s+\w+",  # Object definitions
			r"^def\s+\w+",  # Method definitions
			r"^val\s+\w+",  # Val declarations
			r"^var\s+\w+",  # Var declarations
		],
	}

	# Return pattern strings for the language or empty list if not supported
	return pattern_strings.get(language, [])

determine_commit_type

determine_commit_type(files: list[str]) -> str

Determine the appropriate commit type based on the files.

Parameters:

Name	Type	Description	Default
files	list[str]	List of file paths	required

Returns:

Type	Description
str	Commit type string (e.g., "feat", "fix", "test", "docs", "chore")

Source code in src/codemap/git/diff_splitter/utils.py

def determine_commit_type(files: list[str]) -> str:
	"""
	Determine the appropriate commit type based on the files.

	Args:
	    files: List of file paths

	Returns:
	    Commit type string (e.g., "feat", "fix", "test", "docs", "chore")

	"""
	# Check for test files
	if any(f.startswith("tests/") or "_test." in f or "test_" in f for f in files):
		return "test"

	# Check for documentation files
	if any(f.startswith("docs/") or f.endswith(".md") for f in files):
		return "docs"

	# Check for configuration files
	if any(f.endswith((".json", ".yml", ".yaml", ".toml", ".ini", ".cfg")) for f in files):
		return "chore"

	# Default to "chore" for general updates
	return "chore"

create_chunk_description

create_chunk_description(
	commit_type: str, files: list[str]
) -> str

Create a meaningful description for a chunk.

Parameters:

Name	Type	Description	Default
commit_type	str	Type of commit (e.g., "feat", "fix")	required
files	list[str]	List of file paths	required

Returns:

Type	Description
str	Description string

Source code in src/codemap/git/diff_splitter/utils.py

def create_chunk_description(commit_type: str, files: list[str]) -> str:
	"""
	Create a meaningful description for a chunk.

	Args:
	    commit_type: Type of commit (e.g., "feat", "fix")
	    files: List of file paths

	Returns:
	    Description string

	"""
	if len(files) == 1:
		return f"{commit_type}: update {files[0]}"

	# Try to find a common directory using Path for better cross-platform compatibility
	try:
		common_dir = Path(os.path.commonpath(files))
		if str(common_dir) not in (".", ""):
			return f"{commit_type}: update files in {common_dir}"
	except ValueError:
		# commonpath raises ValueError if files are on different drives
		pass

	return f"{commit_type}: update {len(files)} related files"

get_deleted_tracked_files

get_deleted_tracked_files() -> tuple[set, set]

Get list of deleted but tracked files from git status.

Returns:

Type	Description
tuple[set, set]	Tuple of (deleted_unstaged_files, deleted_staged_files) as sets

Source code in src/codemap/git/diff_splitter/utils.py

def get_deleted_tracked_files() -> tuple[set, set]:
	"""
	Get list of deleted but tracked files from git status.

	Returns:
	    Tuple of (deleted_unstaged_files, deleted_staged_files) as sets

	"""
	deleted_unstaged_files = set()
	deleted_staged_files = set()
	try:
		# Parse git status to find deleted files
		status_output = run_git_command(["git", "status", "--porcelain"])
		for line in status_output.splitlines():
			if line.startswith(" D"):
				# Unstaged deletion (space followed by D)
				filename = line[3:].strip()  # Skip " D " prefix and strip any whitespace
				deleted_unstaged_files.add(filename)
			elif line.startswith("D "):
				# Staged deletion (D followed by space)
				filename = line[2:].strip()  # Skip "D " prefix and strip any whitespace
				deleted_staged_files.add(filename)
		logger.debug("Found %d deleted unstaged files in git status", len(deleted_unstaged_files))
		logger.debug("Found %d deleted staged files in git status", len(deleted_staged_files))
	except GitError as e:  # Catch specific GitError from run_git_command
		logger.warning("Failed to get git status for deleted files: %s. Proceeding without deleted file info.", e)
	except Exception:  # Catch any other unexpected error
		logger.exception("Unexpected error getting git status: %s. Proceeding without deleted file info.")

	return deleted_unstaged_files, deleted_staged_files

filter_valid_files

filter_valid_files(
	files: list[str], is_test_environment: bool = False
) -> tuple[list[str], list[str]]

Filter invalid filenames and files based on existence and Git tracking.

Parameters:

Name	Type	Description	Default
files	list[str]	List of file paths to filter	required
is_test_environment	bool	Whether running in a test environment	False

Returns:

Type	Description
tuple[list[str], list[str]]	Tuple of (valid_files, empty_list) - The second element is always an empty list now.

Source code in src/codemap/git/diff_splitter/utils.py

def filter_valid_files(files: list[str], is_test_environment: bool = False) -> tuple[list[str], list[str]]:
	"""
	Filter invalid filenames and files based on existence and Git tracking.

	Args:
	    files: List of file paths to filter
	    is_test_environment: Whether running in a test environment

	Returns:
	    Tuple of (valid_files, empty_list) - The second element is always an empty list now.

	"""
	if not files:
		return [], []

	valid_files_intermediate = []
	# Keep track of files filtered due to large size if needed elsewhere,
	# but don't remove them from processing yet.

	for file in files:
		# Skip files that look like patterns or templates
		if any(char in file for char in ["*", "+", "{", "}", "\\"]) or file.startswith('"'):
			logger.warning("Skipping invalid filename in diff processing: %s", file)
			continue
		valid_files_intermediate.append(file)

	# --- File Existence and Git Tracking Checks ---
	valid_files = []  # Reset valid_files to populate after existence checks

	# Skip file existence checks in test environments
	if is_test_environment:
		logger.debug("In test environment - skipping file existence checks for %d files", len(valid_files_intermediate))
		# In test env, assume all intermediate files are valid regarding existence/tracking
		valid_files = valid_files_intermediate
	else:
		# Get deleted files
		deleted_unstaged_files, deleted_staged_files = get_deleted_tracked_files()

		# Check if files exist in the repository (tracked by git) or filesystem
		original_count = len(valid_files_intermediate)
		try:
			tracked_files_output = run_git_command(["git", "ls-files"])
			tracked_files = set(tracked_files_output.splitlines())

			# Keep files that either:
			# 1. Exist in filesystem
			# 2. Are tracked by git
			# 3. Are known deleted files from git status
			# 4. Are already staged deletions
			filtered_files = []
			for file in valid_files_intermediate:
				try:
					path_exists = Path(file).exists()
				except OSError as e:
					logger.warning("OS error checking existence for %s: %s. Skipping file.", file, e)
					continue
				except Exception:
					logger.exception("Unexpected error checking existence for %s. Skipping file.", file)
					continue

				if (
					path_exists
					or file in tracked_files
					or file in deleted_unstaged_files
					or file in deleted_staged_files
				):
					filtered_files.append(file)
				else:
					logger.warning("Skipping non-existent/untracked/not-deleted file in diff: %s", file)

			valid_files = filtered_files
			if len(valid_files) < original_count:
				logger.warning(
					"Filtered out %d files that don't exist or aren't tracked/deleted",
					original_count - len(valid_files),
				)
		except GitError as e:  # Catch GitError from run_git_command
			logger.warning("Failed to get tracked files from git: %s. Filtering based on existence only.", e)
			# If we can't check git tracked files, filter by filesystem existence and git status
			filtered_files_fallback = []
			for file in valid_files_intermediate:
				try:
					path_exists = Path(file).exists()
				except OSError as e:
					logger.warning("OS error checking existence for %s: %s. Skipping file.", file, e)
					continue
				except Exception:
					logger.exception("Unexpected error checking existence for %s. Skipping file.", file)
					continue

				if path_exists or file in deleted_unstaged_files or file in deleted_staged_files:
					filtered_files_fallback.append(file)
				else:
					logger.warning("Skipping non-existent/not-deleted file in diff (git check failed): %s", file)

			valid_files = filtered_files_fallback  # Replace valid_files with the fallback list
			if len(valid_files) < original_count:
				# Adjust log message if git check failed
				logger.warning(
					"Filtered out %d files that don't exist (git check failed)",
					original_count - len(valid_files),
				)
		except Exception:  # Catch any other unexpected errors during the initial try block
			logger.exception("Unexpected error during file filtering. Proceeding with potentially incorrect list.")
			# If a catastrophic error occurs, proceed with the intermediate list
			valid_files = valid_files_intermediate

	# Return only the list of valid files. The concept of 'filtered_large_files' is removed.
	# Size checking will now happen within the splitting strategy.
	return valid_files, []  # Return empty list for the second element now.

is_test_environment

is_test_environment() -> bool

Check if the code is running in a test environment.

Returns:

Type	Description
bool	True if in a test environment, False otherwise

Source code in src/codemap/git/diff_splitter/utils.py

def is_test_environment() -> bool:
	"""
	Check if the code is running in a test environment.

	Returns:
	    True if in a test environment, False otherwise

	"""
	# Check multiple environment indicators for tests
	return "PYTEST_CURRENT_TEST" in os.environ or "pytest" in sys.modules or os.environ.get("TESTING") == "1"

calculate_semantic_similarity

calculate_semantic_similarity(
	emb1: list[float], emb2: list[float]
) -> float

Calculate semantic similarity (cosine similarity) between two embedding vectors.

Parameters:

Name	Type	Description	Default
emb1	list[float]	First embedding vector	required
emb2	list[float]	Second embedding vector	required

Returns:

Type	Description
float	Similarity score between 0 and 1

Source code in src/codemap/git/diff_splitter/utils.py

def calculate_semantic_similarity(emb1: list[float], emb2: list[float]) -> float:
	"""
	Calculate semantic similarity (cosine similarity) between two embedding vectors.

	Args:
	    emb1: First embedding vector
	    emb2: Second embedding vector

	Returns:
	    Similarity score between 0 and 1

	"""
	if not emb1 or not emb2:
		return 0.0

	try:
		# Convert to numpy arrays
		vec1 = np.array(emb1, dtype=np.float64)
		vec2 = np.array(emb2, dtype=np.float64)

		# Calculate cosine similarity
		dot_product = np.dot(vec1, vec2)
		norm1 = np.linalg.norm(vec1)
		norm2 = np.linalg.norm(vec2)

		if norm1 <= EPSILON or norm2 <= EPSILON:
			return 0.0

		similarity = float(dot_product / (norm1 * norm2))

		# Handle potential numeric issues
		if not np.isfinite(similarity):
			return 0.0

		return max(0.0, min(1.0, similarity))  # Clamp to [0, 1]

	except (ValueError, TypeError, ArithmeticError, OverflowError):
		logger.warning("Failed to calculate similarity")
		return 0.0

match_test_file_patterns

match_test_file_patterns(file1: str, file2: str) -> bool

Check if files match common test file patterns.

Source code in src/codemap/git/diff_splitter/utils.py

def match_test_file_patterns(file1: str, file2: str) -> bool:
	"""Check if files match common test file patterns."""
	# test_X.py and X.py patterns
	if file1.startswith("test_") and file1[5:] == file2:
		return True
	if file2.startswith("test_") and file2[5:] == file1:
		return True

	# X_test.py and X.py patterns
	if file1.endswith("_test.py") and file1[:-8] + ".py" == file2:
		return True
	return bool(file2.endswith("_test.py") and file2[:-8] + ".py" == file1)

have_similar_names

have_similar_names(file1: str, file2: str) -> bool

Check if files have similar base names.

Source code in src/codemap/git/diff_splitter/utils.py

def have_similar_names(file1: str, file2: str) -> bool:
	"""Check if files have similar base names."""
	base1 = file1.rsplit(".", 1)[0] if "." in file1 else file1
	base2 = file2.rsplit(".", 1)[0] if "." in file2 else file2

	return (base1 in base2 or base2 in base1) and min(len(base1), len(base2)) >= MIN_NAME_LENGTH_FOR_SIMILARITY

has_related_file_pattern

has_related_file_pattern(
	file1: str,
	file2: str,
	related_file_patterns: Iterable[
		tuple[Pattern, Pattern]
	],
) -> bool

Check if files match known related patterns.

Parameters:

Name	Type	Description	Default
file1	str	First file path	required
file2	str	Second file path	required
related_file_patterns	Iterable[tuple[Pattern, Pattern]]	Compiled regex pattern pairs to check against	required

Returns:

Type	Description
bool	True if the files match a known pattern, False otherwise

Source code in src/codemap/git/diff_splitter/utils.py

def has_related_file_pattern(file1: str, file2: str, related_file_patterns: Iterable[tuple[Pattern, Pattern]]) -> bool:
	"""
	Check if files match known related patterns.

	Args:
	    file1: First file path
	    file2: Second file path
	    related_file_patterns: Compiled regex pattern pairs to check against

	Returns:
	    True if the files match a known pattern, False otherwise

	"""
	for pattern1, pattern2 in related_file_patterns:
		if (pattern1.match(file1) and pattern2.match(file2)) or (pattern2.match(file1) and pattern1.match(file2)):
			return True
	return False

are_files_related

are_files_related(
	file1: str,
	file2: str,
	related_file_patterns: Iterable[
		tuple[Pattern, Pattern]
	],
) -> bool

Determine if two files are semantically related based on various criteria.

Parameters:

Name	Type	Description	Default
file1	str	First file path	required
file2	str	Second file path	required
related_file_patterns	Iterable[tuple[Pattern, Pattern]]	Compiled regex pattern pairs for pattern matching	required

Returns:

Type	Description
bool	True if the files are related, False otherwise

Source code in src/codemap/git/diff_splitter/utils.py

def are_files_related(file1: str, file2: str, related_file_patterns: Iterable[tuple[Pattern, Pattern]]) -> bool:
	"""
	Determine if two files are semantically related based on various criteria.

	Args:
	    file1: First file path
	    file2: Second file path
	    related_file_patterns: Compiled regex pattern pairs for pattern matching

	Returns:
	    True if the files are related, False otherwise

	"""
	# 1. Files in the same directory
	dir1 = file1.rsplit("/", 1)[0] if "/" in file1 else ""
	dir2 = file2.rsplit("/", 1)[0] if "/" in file2 else ""
	if dir1 and dir1 == dir2:
		return True

	# 2. Files in closely related directories (parent/child or same root directory)
	if dir1 and dir2:
		if dir1.startswith(dir2 + "/") or dir2.startswith(dir1 + "/"):
			return True
		# Check if they share the same top-level directory
		top_dir1 = dir1.split("/", 1)[0] if "/" in dir1 else dir1
		top_dir2 = dir2.split("/", 1)[0] if "/" in dir2 else dir2
		if top_dir1 and top_dir1 == top_dir2:
			return True

	# 3. Test files and implementation files (simple check)
	if (file1.startswith("tests/") and file2 in file1) or (file2.startswith("tests/") and file1 in file2):
		return True

	# 4. Test file patterns
	file1_name = file1.rsplit("/", 1)[-1] if "/" in file1 else file1
	file2_name = file2.rsplit("/", 1)[-1] if "/" in file2 else file2
	if match_test_file_patterns(file1_name, file2_name):
		return True

	# 5. Files with similar names
	if have_similar_names(file1_name, file2_name):
		return True

	# 6. Check for related file patterns
	return has_related_file_pattern(file1, file2, related_file_patterns)

splitter

Diff splitting implementation for CodeMap.

logger module-attribute

logger = getLogger(__name__)

MAX_DIFF_CONTENT_LENGTH module-attribute

MAX_DIFF_CONTENT_LENGTH = 100000

MAX_DIFF_LINES module-attribute

MAX_DIFF_LINES = 1000

SMALL_SECTION_SIZE module-attribute

SMALL_SECTION_SIZE = 50

COMPLEX_SECTION_SIZE module-attribute

COMPLEX_SECTION_SIZE = 100

DiffSplitter

Splits Git diffs into logical chunks.

Source code in src/codemap/git/diff_splitter/splitter.py

class DiffSplitter:
	"""Splits Git diffs into logical chunks."""

	# Class-level cache for the embedding model
	_embedding_model = None
	# Track availability of sentence-transformers and the model
	_sentence_transformers_available = None
	_model_available = None

	def __init__(
		self,
		repo_root: Path,
		# Defaults are now sourced from DEFAULT_CONFIG
		similarity_threshold: float = DEFAULT_CONFIG["commit"]["diff_splitter"]["similarity_threshold"],
		directory_similarity_threshold: float = DEFAULT_CONFIG["commit"]["diff_splitter"][
			"directory_similarity_threshold"
		],
		min_chunks_for_consolidation: int = DEFAULT_CONFIG["commit"]["diff_splitter"]["min_chunks_for_consolidation"],
		max_chunks_before_consolidation: int = DEFAULT_CONFIG["commit"]["diff_splitter"][
			"max_chunks_before_consolidation"
		],
		max_file_size_for_llm: int = DEFAULT_CONFIG["commit"]["diff_splitter"]["max_file_size_for_llm"],
		max_log_diff_size: int = DEFAULT_CONFIG["commit"]["diff_splitter"]["max_log_diff_size"],
		model_name: str = DEFAULT_CONFIG["commit"]["diff_splitter"]["model_name"],
	) -> None:
		"""
		Initialize the diff splitter.

		Args:
		    repo_root: Root directory of the Git repository
		    similarity_threshold: Threshold for grouping by content similarity.
		    directory_similarity_threshold: Threshold for directory similarity.
		    min_chunks_for_consolidation: Min chunks to trigger consolidation.
		    max_chunks_before_consolidation: Max chunks allowed before forced consolidation.
		    max_file_size_for_llm: Max file size (bytes) to process for LLM context.
		        Defaults to value from `DEFAULT_CONFIG["commit"]["diff_splitter"]["max_file_size_for_llm"]` if None.
		    max_log_diff_size: Max diff size (bytes) to log in debug mode.
		        Defaults to value from `DEFAULT_CONFIG["commit"]["diff_splitter"]["max_log_diff_size"]` if None.
		    model_name: Name of the sentence-transformer model to use.
		        Defaults to value from `DEFAULT_CONFIG["commit"]["diff_splitter"]["model_name"]` if None.

		"""
		self.repo_root = repo_root
		# Store thresholds
		self.similarity_threshold = similarity_threshold
		self.directory_similarity_threshold = directory_similarity_threshold
		self.min_chunks_for_consolidation = min_chunks_for_consolidation
		self.max_chunks_before_consolidation = max_chunks_before_consolidation
		# Store other settings
		self.max_file_size_for_llm = max_file_size_for_llm
		self.max_log_diff_size = max_log_diff_size
		self.model_name = model_name

		# Do NOT automatically check availability - let the command class do this explicitly
		# This avoids checks happening during initialization without visible loading states

	@classmethod
	def _check_sentence_transformers_availability(cls) -> bool:
		"""
		Check if sentence-transformers package is available.

		Returns:
		    True if sentence-transformers is available, False otherwise

		"""
		try:
			# This is needed for the import check, but don't flag as unused
			import sentence_transformers  # type: ignore  # noqa: F401, PGH003

			# Set the class flag for future reference
			cls._sentence_transformers_available = True
			logger.debug("sentence-transformers is available")
			return True
		except ImportError as e:
			# Log the specific import error for better debugging
			cls._sentence_transformers_available = False
			logger.warning(
				"sentence-transformers import failed: %s. Semantic similarity features will be limited. "
				"Install with: pip install sentence-transformers numpy",
				e,
			)
			return False
		except (RuntimeError, ValueError, AttributeError) as e:
			# Catch specific errors during import
			cls._sentence_transformers_available = False
			logger.warning(
				"Unexpected error importing sentence-transformers: %s. Semantic similarity features will be limited.", e
			)
			return False

	@classmethod
	def are_sentence_transformers_available(cls) -> bool:
		"""
		Check if sentence transformers are available.

		Returns:
		    True if sentence transformers are available, False otherwise

		"""
		return cls._sentence_transformers_available or cls._check_sentence_transformers_availability()

	@classmethod
	def is_model_available(cls) -> bool:
		"""
		Check if embedding model is available.

		Returns:
		    True if embedding model is available, False otherwise

		"""
		return bool(cls._model_available)

	@classmethod
	def set_model_available(cls, value: bool) -> None:
		"""
		Set model availability flag.

		Args:
		    value: Boolean indicating if model is available

		"""
		cls._model_available = value

	@classmethod
	def get_embedding_model(cls) -> EmbeddingModel | None:
		"""
		Get the embedding model.

		Returns:
		    The embedding model or None if not available

		"""
		return cls._embedding_model

	@classmethod
	def set_embedding_model(cls, model: EmbeddingModel) -> None:
		"""
		Set the embedding model.

		Args:
		    model: The embedding model to set

		"""
		cls._embedding_model = model

	def _check_model_availability(self) -> bool:
		"""
		Check if the embedding model is available using the instance's configured model name.

		Returns:
		    True if model is available, False otherwise

		"""
		# Use class method to access class-level cache check
		if not self.__class__.are_sentence_transformers_available():
			return False

		try:
			from sentence_transformers import SentenceTransformer

			# Use class method to access class-level cache
			if self.__class__.get_embedding_model() is None:
				# Use self.model_name from instance configuration
				logger.debug("Loading embedding model: %s", self.model_name)

				try:
					console.print("Loading embedding model...")
					# Load the model using self.model_name
					model = SentenceTransformer(self.model_name)
					self.__class__.set_embedding_model(cast("EmbeddingModel", model))
					console.print("[green]✓[/green] Model loaded successfully")
					logger.debug("Initialized embedding model: %s", self.model_name)
					# Set class-level flag via class method
					self.__class__.set_model_available(True)
					return True
				except ImportError as e:
					logger.exception("Missing dependencies for embedding model")
					console.print(f"[red]Error: Missing dependencies: {e}[/red]")
					self.__class__.set_model_available(False)
					return False
				except MemoryError:
					logger.exception("Not enough memory to load embedding model")
					console.print("[red]Error: Not enough memory to load embedding model[/red]")
					self.__class__.set_model_available(False)
					return False
				except ValueError as e:
					logger.exception("Invalid model configuration")
					console.print(f"[red]Error: Invalid model configuration: {e}[/red]")
					self.__class__.set_model_available(False)
					return False
				except RuntimeError as e:
					error_msg = str(e)
					# Check for CUDA/GPU related errors
					if "CUDA" in error_msg or "GPU" in error_msg:
						logger.exception("GPU error when loading model")
						console.print("[red]Error: GPU/CUDA error. Try using CPU only mode.[/red]")
					else:
						logger.exception("Runtime error when loading model")
						console.print(f"[red]Error loading model: {error_msg}[/red]")
					self.__class__.set_model_available(False)
					return False
				except Exception as e:
					logger.exception("Unexpected error loading embedding model")
					console.print(f"[red]Unexpected error loading model: {e}[/red]")
					self.__class__.set_model_available(False)
					return False
			# If we already have a model loaded, make sure to set the flag to True
			self.__class__.set_model_available(True)
			return True
		except Exception as e:
			# This is the outer exception handler for any unexpected errors
			logger.exception("Failed to load embedding model %s", self.model_name)
			console.print(f"[red]Failed to load embedding model: {e}[/red]")
			self.__class__.set_model_available(False)
			return False

	def split_diff(self, diff: GitDiff) -> tuple[list[DiffChunk], list[str]]:
		"""
		Split a diff into logical chunks using semantic splitting.

		Args:
		    diff: GitDiff object to split

		Returns:
		    Tuple of (List of DiffChunk objects based on semantic analysis, List of filtered large files)

		Raises:
		    ValueError: If semantic splitting is not available or fails

		"""
		if not diff.files:
			return [], []

		# Special handling for untracked files - bypass semantic split since the content isn't a proper diff format
		if diff.is_untracked:
			logger.debug("Processing untracked files with special handling: %d files", len(diff.files))
			# Create a simple chunk per file to avoid errors with unidiff parsing
			chunks = []
			for file_path in diff.files:
				# Create a basic chunk with file info but without trying to parse the content as a diff
				chunks = [
					DiffChunk(
						files=[file_path],
						content=f"New untracked file: {file_path}",
						description=f"New file: {file_path}",
					)
					for file_path in diff.files
				]
			return chunks, []

		# In test environments, log the diff content for debugging
		if is_test_environment():
			logger.debug("Processing diff in test environment with %d files", len(diff.files) if diff.files else 0)
			if diff.content and len(diff.content) < self.max_log_diff_size:  # Use configured max log size
				logger.debug("Diff content: %s", diff.content)

		# Process files in the diff
		if diff.files:
			# Filter for valid files (existence, tracked status), max_size check removed here
			diff.files, _ = filter_valid_files(diff.files, is_test_environment())
			# filtered_large_files list is no longer populated or used here

		if not diff.files:
			logger.warning("No valid files to process after filtering")
			return [], []  # Return empty lists

		# Set up availability flags if not already set
		# Use class method to check sentence transformers availability
		if not self.__class__.are_sentence_transformers_available():
			msg = (
				"Semantic splitting is not available. sentence-transformers package is required. "
				"Install with: pip install sentence-transformers numpy"
			)
			raise ValueError(msg)

		# Try to load the model using the instance method
		with loading_spinner("Loading embedding model..."):
			# Use self._check_model_availability() - it uses self.model_name internally
			if not self.__class__.is_model_available():
				self._check_model_availability()

		if not self.__class__.is_model_available():
			msg = "Semantic splitting failed: embedding model could not be loaded. Check logs for details."
			raise ValueError(msg)

		try:
			chunks = self._split_semantic(diff)

			# If we truncated the content, restore the original content for the actual chunks
			if diff.content and chunks:
				# Create a mapping of file paths to chunks for quick lookup
				chunks_by_file = {}
				for chunk in chunks:
					for file_path in chunk.files:
						if file_path not in chunks_by_file:
							chunks_by_file[file_path] = []
						chunks_by_file[file_path].append(chunk)

				# For chunks that represent files we can find in the original content,
				# update their content to include the full original diff for that file
				for chunk in chunks:
					# Use a heuristic to match file sections in the original content
					for file_path in chunk.files:
						file_marker = f"diff --git a/{file_path} b/{file_path}"
						if file_marker in diff.content:
							# Found a match for this file in the original content
							# Extract that file's complete diff section
							start_idx = diff.content.find(file_marker)
							end_idx = diff.content.find("diff --git", start_idx + len(file_marker))
							if end_idx == -1:  # Last file in the diff
								end_idx = len(diff.content)

							file_diff = diff.content[start_idx:end_idx].strip()

							# Now replace just this file's content in the chunk
							# This is a heuristic that may need adjustment based on your diff format
							if chunk.content and file_marker in chunk.content:
								chunk_start = chunk.content.find(file_marker)
								chunk_end = chunk.content.find("diff --git", chunk_start + len(file_marker))
								if chunk_end == -1:  # Last file in the chunk
									chunk_end = len(chunk.content)

								# Replace this file's truncated diff with the full diff
								chunk.content = chunk.content[:chunk_start] + file_diff + chunk.content[chunk_end:]

			return chunks, []
		except Exception as e:
			logger.exception("Semantic splitting failed")
			console.print(f"[red]Semantic splitting failed: {e}[/red]")

			# Try basic splitting as a fallback
			logger.warning("Falling back to basic file splitting")
			console.print("[yellow]Falling back to basic file splitting[/yellow]")
			# Return empty list for filtered_large_files as it's no longer tracked here
			return self._create_basic_file_chunk(diff), []

	def _create_basic_file_chunk(self, diff: GitDiff) -> list[DiffChunk]:
		"""
		Create a basic chunk per file without semantic analysis.

		Args:
		    diff: GitDiff object to split

		Returns:
		    List of DiffChunk objects, one per file

		"""
		chunks = []

		if diff.files:
			# Create a basic chunk, one per file in this strategy, no semantic grouping
			strategy = FileSplitStrategy()
			chunks = strategy.split(diff)

		return chunks

	def _split_semantic(self, diff: GitDiff) -> list[DiffChunk]:
		"""
		Perform semantic splitting, falling back if needed.

		Args:
		    diff: GitDiff object to split

		Returns:
		    List of DiffChunk objects

		Raises:
		    ValueError: If semantic splitting fails and fallback is not possible.

		"""
		if not self.are_sentence_transformers_available():
			logger.warning("Sentence transformers unavailable. Falling back to file-based splitting.")
			# Directly use FileSplitStrategy when ST is unavailable
			file_splitter = FileSplitStrategy()
			return file_splitter.split(diff)

		# Existing logic for semantic splitting when ST is available
		try:
			semantic_strategy = SemanticSplitStrategy(embedding_model=self._embedding_model)
			return semantic_strategy.split(diff)
		except Exception:
			logger.exception("Semantic splitting failed: %s. Falling back to file splitting.")
			# Fallback to FileSplitStrategy on any semantic splitting error
			file_splitter = FileSplitStrategy()
			return file_splitter.split(diff)

	def _calculate_semantic_similarity(self, text1: str, text2: str) -> float:
		"""
		Calculate semantic similarity between two texts using the embedding model.

		Args:
		    text1: First text
		    text2: Second text

		Returns:
		    Similarity score between 0 and 1

		"""
		# Check if embedding model is available
		if not self.__class__.are_sentence_transformers_available():
			logger.debug("Sentence transformers not available, returning zero similarity")
			return 0.0

		# Call instance method self._check_model_availability()
		if not self.__class__.is_model_available():
			self._check_model_availability()

		if not self.__class__.is_model_available() or self.__class__.get_embedding_model() is None:
			logger.debug("Embedding model not available, returning zero similarity")
			return 0.0

		# Assign to local variable after check guarantees it's not None
		embedding_model_maybe_none = self.__class__.get_embedding_model()
		if embedding_model_maybe_none is None:
			# This case should have been caught earlier, but log just in case
			logger.error("Embedding model unexpectedly None after availability check")
			return 0.0

		embedding_model = embedding_model_maybe_none  # Now we know it's not None

		try:
			# Get embeddings for both texts
			emb1 = embedding_model.encode([text1])[0]
			emb2 = embedding_model.encode([text2])[0]

			# Calculate similarity using numpy
			return calculate_semantic_similarity(emb1.tolist(), emb2.tolist())
		except (ValueError, TypeError, IndexError, RuntimeError) as e:
			logger.warning("Failed to calculate semantic similarity: %s", e)
			return 0.0

	def encode_chunks(self, chunks: list[str]) -> dict[str, np.ndarray]:
		"""
		Encode a list of text chunks using the embedding model.

		Args:
		    chunks: List of text chunks to encode

		Returns:
		    Dictionary with embeddings array

		"""
		# Ensure the model is initialized
		if self.__class__.are_sentence_transformers_available() and not self.__class__.is_model_available():
			self._check_model_availability()

		if not self.__class__.is_model_available():
			logger.debug("Embedding model not available, returning empty embeddings")
			return {"embeddings": np.array([])}

		# Skip empty chunks
		if not chunks:
			logger.debug("No chunks to encode")
			return {"embeddings": np.array([])}

		# Use class method for class cache access
		if self.__class__.get_embedding_model() is None:
			logger.debug("Embedding model is None but was marked as available, reinitializing")
			# Re-check availability using instance method
			self._check_model_availability()

		# Check again after potential re-initialization and assign to local variable
		if self.__class__.get_embedding_model() is None:
			logger.error("Embedding model is still None after re-check")
			return {"embeddings": np.array([])}

		# Explicitly cast after the check
		embedding_model_maybe_none = self.__class__.get_embedding_model()
		if embedding_model_maybe_none is None:
			logger.error("Embedding model unexpectedly None in encode_chunks")
			return {"embeddings": np.array([])}

		embedding_model = embedding_model_maybe_none  # Now we know it's not None

		try:
			logger.debug("Encoding %d chunks", len(chunks))
			embeddings = embedding_model.encode(chunks)
			logger.debug("Successfully encoded %d chunks to shape %s", len(chunks), embeddings.shape)
			return {"embeddings": embeddings}
		except Exception:
			logger.exception("Error encoding chunks")
			return {"embeddings": np.array([])}  # Return empty on error

__init__

__init__(
	repo_root: Path,
	similarity_threshold: float = DEFAULT_CONFIG["commit"][
		"diff_splitter"
	]["similarity_threshold"],
	directory_similarity_threshold: float = DEFAULT_CONFIG[
		"commit"
	]["diff_splitter"]["directory_similarity_threshold"],
	min_chunks_for_consolidation: int = DEFAULT_CONFIG[
		"commit"
	]["diff_splitter"]["min_chunks_for_consolidation"],
	max_chunks_before_consolidation: int = DEFAULT_CONFIG[
		"commit"
	]["diff_splitter"]["max_chunks_before_consolidation"],
	max_file_size_for_llm: int = DEFAULT_CONFIG["commit"][
		"diff_splitter"
	]["max_file_size_for_llm"],
	max_log_diff_size: int = DEFAULT_CONFIG["commit"][
		"diff_splitter"
	]["max_log_diff_size"],
	model_name: str = DEFAULT_CONFIG["commit"][
		"diff_splitter"
	]["model_name"],
) -> None

Initialize the diff splitter.

Parameters:

Name	Type	Description	Default
repo_root	Path	Root directory of the Git repository	required
similarity_threshold	float	Threshold for grouping by content similarity.	DEFAULT_CONFIG['commit']['diff_splitter']['similarity_threshold']
directory_similarity_threshold	float	Threshold for directory similarity.	DEFAULT_CONFIG['commit']['diff_splitter']['directory_similarity_threshold']
min_chunks_for_consolidation	int	Min chunks to trigger consolidation.	DEFAULT_CONFIG['commit']['diff_splitter']['min_chunks_for_consolidation']
max_chunks_before_consolidation	int	Max chunks allowed before forced consolidation.	DEFAULT_CONFIG['commit']['diff_splitter']['max_chunks_before_consolidation']
max_file_size_for_llm	int	Max file size (bytes) to process for LLM context. Defaults to value from DEFAULT_CONFIG["commit"]["diff_splitter"]["max_file_size_for_llm"] if None.	DEFAULT_CONFIG['commit']['diff_splitter']['max_file_size_for_llm']
max_log_diff_size	int	Max diff size (bytes) to log in debug mode. Defaults to value from DEFAULT_CONFIG["commit"]["diff_splitter"]["max_log_diff_size"] if None.	DEFAULT_CONFIG['commit']['diff_splitter']['max_log_diff_size']
model_name	str	Name of the sentence-transformer model to use. Defaults to value from DEFAULT_CONFIG["commit"]["diff_splitter"]["model_name"] if None.	DEFAULT_CONFIG['commit']['diff_splitter']['model_name']

Source code in src/codemap/git/diff_splitter/splitter.py

def __init__(
	self,
	repo_root: Path,
	# Defaults are now sourced from DEFAULT_CONFIG
	similarity_threshold: float = DEFAULT_CONFIG["commit"]["diff_splitter"]["similarity_threshold"],
	directory_similarity_threshold: float = DEFAULT_CONFIG["commit"]["diff_splitter"][
		"directory_similarity_threshold"
	],
	min_chunks_for_consolidation: int = DEFAULT_CONFIG["commit"]["diff_splitter"]["min_chunks_for_consolidation"],
	max_chunks_before_consolidation: int = DEFAULT_CONFIG["commit"]["diff_splitter"][
		"max_chunks_before_consolidation"
	],
	max_file_size_for_llm: int = DEFAULT_CONFIG["commit"]["diff_splitter"]["max_file_size_for_llm"],
	max_log_diff_size: int = DEFAULT_CONFIG["commit"]["diff_splitter"]["max_log_diff_size"],
	model_name: str = DEFAULT_CONFIG["commit"]["diff_splitter"]["model_name"],
) -> None:
	"""
	Initialize the diff splitter.

	Args:
	    repo_root: Root directory of the Git repository
	    similarity_threshold: Threshold for grouping by content similarity.
	    directory_similarity_threshold: Threshold for directory similarity.
	    min_chunks_for_consolidation: Min chunks to trigger consolidation.
	    max_chunks_before_consolidation: Max chunks allowed before forced consolidation.
	    max_file_size_for_llm: Max file size (bytes) to process for LLM context.
	        Defaults to value from `DEFAULT_CONFIG["commit"]["diff_splitter"]["max_file_size_for_llm"]` if None.
	    max_log_diff_size: Max diff size (bytes) to log in debug mode.
	        Defaults to value from `DEFAULT_CONFIG["commit"]["diff_splitter"]["max_log_diff_size"]` if None.
	    model_name: Name of the sentence-transformer model to use.
	        Defaults to value from `DEFAULT_CONFIG["commit"]["diff_splitter"]["model_name"]` if None.

	"""
	self.repo_root = repo_root
	# Store thresholds
	self.similarity_threshold = similarity_threshold
	self.directory_similarity_threshold = directory_similarity_threshold
	self.min_chunks_for_consolidation = min_chunks_for_consolidation
	self.max_chunks_before_consolidation = max_chunks_before_consolidation
	# Store other settings
	self.max_file_size_for_llm = max_file_size_for_llm
	self.max_log_diff_size = max_log_diff_size
	self.model_name = model_name

repo_root instance-attribute

repo_root = repo_root

similarity_threshold instance-attribute

similarity_threshold = similarity_threshold

directory_similarity_threshold instance-attribute

directory_similarity_threshold = (
	directory_similarity_threshold
)

min_chunks_for_consolidation instance-attribute

min_chunks_for_consolidation = min_chunks_for_consolidation

max_chunks_before_consolidation instance-attribute

max_chunks_before_consolidation = (
	max_chunks_before_consolidation
)

max_file_size_for_llm instance-attribute

max_file_size_for_llm = max_file_size_for_llm

max_log_diff_size instance-attribute

max_log_diff_size = max_log_diff_size

model_name instance-attribute

model_name = model_name

are_sentence_transformers_available classmethod

are_sentence_transformers_available() -> bool

Check if sentence transformers are available.

Returns:

Type	Description
bool	True if sentence transformers are available, False otherwise

Source code in src/codemap/git/diff_splitter/splitter.py

@classmethod
def are_sentence_transformers_available(cls) -> bool:
	"""
	Check if sentence transformers are available.

	Returns:
	    True if sentence transformers are available, False otherwise

	"""
	return cls._sentence_transformers_available or cls._check_sentence_transformers_availability()

is_model_available classmethod

is_model_available() -> bool

Check if embedding model is available.

Returns:

Type	Description
bool	True if embedding model is available, False otherwise

Source code in src/codemap/git/diff_splitter/splitter.py

@classmethod
def is_model_available(cls) -> bool:
	"""
	Check if embedding model is available.

	Returns:
	    True if embedding model is available, False otherwise

	"""
	return bool(cls._model_available)

set_model_available classmethod

set_model_available(value: bool) -> None

Set model availability flag.

Parameters:

Name	Type	Description	Default
value	bool	Boolean indicating if model is available	required

Source code in src/codemap/git/diff_splitter/splitter.py

@classmethod
def set_model_available(cls, value: bool) -> None:
	"""
	Set model availability flag.

	Args:
	    value: Boolean indicating if model is available

	"""
	cls._model_available = value

get_embedding_model classmethod

get_embedding_model() -> EmbeddingModel | None

Get the embedding model.

Returns:

Type	Description
EmbeddingModel | None	The embedding model or None if not available

Source code in src/codemap/git/diff_splitter/splitter.py

@classmethod
def get_embedding_model(cls) -> EmbeddingModel | None:
	"""
	Get the embedding model.

	Returns:
	    The embedding model or None if not available

	"""
	return cls._embedding_model

set_embedding_model classmethod

set_embedding_model(model: EmbeddingModel) -> None

Set the embedding model.

Parameters:

Name	Type	Description	Default
model	EmbeddingModel	The embedding model to set	required

Source code in src/codemap/git/diff_splitter/splitter.py

@classmethod
def set_embedding_model(cls, model: EmbeddingModel) -> None:
	"""
	Set the embedding model.

	Args:
	    model: The embedding model to set

	"""
	cls._embedding_model = model

split_diff

split_diff(
	diff: GitDiff,
) -> tuple[list[DiffChunk], list[str]]

Split a diff into logical chunks using semantic splitting.

Parameters:

Name	Type	Description	Default
diff	GitDiff	GitDiff object to split	required

Returns:

Type	Description
tuple[list[DiffChunk], list[str]]	Tuple of (List of DiffChunk objects based on semantic analysis, List of filtered large files)

Raises:

Type	Description
ValueError	If semantic splitting is not available or fails

Source code in src/codemap/git/diff_splitter/splitter.py

def split_diff(self, diff: GitDiff) -> tuple[list[DiffChunk], list[str]]:
	"""
	Split a diff into logical chunks using semantic splitting.

	Args:
	    diff: GitDiff object to split

	Returns:
	    Tuple of (List of DiffChunk objects based on semantic analysis, List of filtered large files)

	Raises:
	    ValueError: If semantic splitting is not available or fails

	"""
	if not diff.files:
		return [], []

	# Special handling for untracked files - bypass semantic split since the content isn't a proper diff format
	if diff.is_untracked:
		logger.debug("Processing untracked files with special handling: %d files", len(diff.files))
		# Create a simple chunk per file to avoid errors with unidiff parsing
		chunks = []
		for file_path in diff.files:
			# Create a basic chunk with file info but without trying to parse the content as a diff
			chunks = [
				DiffChunk(
					files=[file_path],
					content=f"New untracked file: {file_path}",
					description=f"New file: {file_path}",
				)
				for file_path in diff.files
			]
		return chunks, []

	# In test environments, log the diff content for debugging
	if is_test_environment():
		logger.debug("Processing diff in test environment with %d files", len(diff.files) if diff.files else 0)
		if diff.content and len(diff.content) < self.max_log_diff_size:  # Use configured max log size
			logger.debug("Diff content: %s", diff.content)

	# Process files in the diff
	if diff.files:
		# Filter for valid files (existence, tracked status), max_size check removed here
		diff.files, _ = filter_valid_files(diff.files, is_test_environment())
		# filtered_large_files list is no longer populated or used here

	if not diff.files:
		logger.warning("No valid files to process after filtering")
		return [], []  # Return empty lists

	# Set up availability flags if not already set
	# Use class method to check sentence transformers availability
	if not self.__class__.are_sentence_transformers_available():
		msg = (
			"Semantic splitting is not available. sentence-transformers package is required. "
			"Install with: pip install sentence-transformers numpy"
		)
		raise ValueError(msg)

	# Try to load the model using the instance method
	with loading_spinner("Loading embedding model..."):
		# Use self._check_model_availability() - it uses self.model_name internally
		if not self.__class__.is_model_available():
			self._check_model_availability()

	if not self.__class__.is_model_available():
		msg = "Semantic splitting failed: embedding model could not be loaded. Check logs for details."
		raise ValueError(msg)

	try:
		chunks = self._split_semantic(diff)

		# If we truncated the content, restore the original content for the actual chunks
		if diff.content and chunks:
			# Create a mapping of file paths to chunks for quick lookup
			chunks_by_file = {}
			for chunk in chunks:
				for file_path in chunk.files:
					if file_path not in chunks_by_file:
						chunks_by_file[file_path] = []
					chunks_by_file[file_path].append(chunk)

			# For chunks that represent files we can find in the original content,
			# update their content to include the full original diff for that file
			for chunk in chunks:
				# Use a heuristic to match file sections in the original content
				for file_path in chunk.files:
					file_marker = f"diff --git a/{file_path} b/{file_path}"
					if file_marker in diff.content:
						# Found a match for this file in the original content
						# Extract that file's complete diff section
						start_idx = diff.content.find(file_marker)
						end_idx = diff.content.find("diff --git", start_idx + len(file_marker))
						if end_idx == -1:  # Last file in the diff
							end_idx = len(diff.content)

						file_diff = diff.content[start_idx:end_idx].strip()

						# Now replace just this file's content in the chunk
						# This is a heuristic that may need adjustment based on your diff format
						if chunk.content and file_marker in chunk.content:
							chunk_start = chunk.content.find(file_marker)
							chunk_end = chunk.content.find("diff --git", chunk_start + len(file_marker))
							if chunk_end == -1:  # Last file in the chunk
								chunk_end = len(chunk.content)

							# Replace this file's truncated diff with the full diff
							chunk.content = chunk.content[:chunk_start] + file_diff + chunk.content[chunk_end:]

		return chunks, []
	except Exception as e:
		logger.exception("Semantic splitting failed")
		console.print(f"[red]Semantic splitting failed: {e}[/red]")

		# Try basic splitting as a fallback
		logger.warning("Falling back to basic file splitting")
		console.print("[yellow]Falling back to basic file splitting[/yellow]")
		# Return empty list for filtered_large_files as it's no longer tracked here
		return self._create_basic_file_chunk(diff), []

encode_chunks

encode_chunks(chunks: list[str]) -> dict[str, ndarray]

Encode a list of text chunks using the embedding model.

Parameters:

Name	Type	Description	Default
chunks	list[str]	List of text chunks to encode	required

Returns:

Type	Description
dict[str, ndarray]	Dictionary with embeddings array

Source code in src/codemap/git/diff_splitter/splitter.py

def encode_chunks(self, chunks: list[str]) -> dict[str, np.ndarray]:
	"""
	Encode a list of text chunks using the embedding model.

	Args:
	    chunks: List of text chunks to encode

	Returns:
	    Dictionary with embeddings array

	"""
	# Ensure the model is initialized
	if self.__class__.are_sentence_transformers_available() and not self.__class__.is_model_available():
		self._check_model_availability()

	if not self.__class__.is_model_available():
		logger.debug("Embedding model not available, returning empty embeddings")
		return {"embeddings": np.array([])}

	# Skip empty chunks
	if not chunks:
		logger.debug("No chunks to encode")
		return {"embeddings": np.array([])}

	# Use class method for class cache access
	if self.__class__.get_embedding_model() is None:
		logger.debug("Embedding model is None but was marked as available, reinitializing")
		# Re-check availability using instance method
		self._check_model_availability()

	# Check again after potential re-initialization and assign to local variable
	if self.__class__.get_embedding_model() is None:
		logger.error("Embedding model is still None after re-check")
		return {"embeddings": np.array([])}

	# Explicitly cast after the check
	embedding_model_maybe_none = self.__class__.get_embedding_model()
	if embedding_model_maybe_none is None:
		logger.error("Embedding model unexpectedly None in encode_chunks")
		return {"embeddings": np.array([])}

	embedding_model = embedding_model_maybe_none  # Now we know it's not None

	try:
		logger.debug("Encoding %d chunks", len(chunks))
		embeddings = embedding_model.encode(chunks)
		logger.debug("Successfully encoded %d chunks to shape %s", len(chunks), embeddings.shape)
		return {"embeddings": embeddings}
	except Exception:
		logger.exception("Error encoding chunks")
		return {"embeddings": np.array([])}  # Return empty on error

constants

Constants for diff splitting functionality.

MIN_NAME_LENGTH_FOR_SIMILARITY module-attribute

MIN_NAME_LENGTH_FOR_SIMILARITY: Final = 3

EPSILON module-attribute

EPSILON = 1e-10

MAX_FILES_PER_GROUP module-attribute

MAX_FILES_PER_GROUP: Final = 10

strategies

Strategies for splitting git diffs into logical chunks.

logger module-attribute

logger = getLogger(__name__)

EXPECTED_TUPLE_SIZE module-attribute

EXPECTED_TUPLE_SIZE = 2

EmbeddingModel

Bases: Protocol

Protocol for embedding models.

Source code in src/codemap/git/diff_splitter/strategies.py

class EmbeddingModel(Protocol):
	"""Protocol for embedding models."""

	def encode(self, texts: Sequence[str], **kwargs: Any) -> np.ndarray:  # noqa: ANN401
		"""Encode texts into embeddings."""
		...

encode

encode(texts: Sequence[str], **kwargs: Any) -> ndarray

Encode texts into embeddings.

Source code in src/codemap/git/diff_splitter/strategies.py

def encode(self, texts: Sequence[str], **kwargs: Any) -> np.ndarray:  # noqa: ANN401
	"""Encode texts into embeddings."""
	...

BaseSplitStrategy

Base class for diff splitting strategies.

Source code in src/codemap/git/diff_splitter/strategies.py

class BaseSplitStrategy:
	"""Base class for diff splitting strategies."""

	def __init__(self, embedding_model: EmbeddingModel | None = None) -> None:
		"""Initialize with optional embedding model."""
		self._embedding_model = embedding_model
		# Precompile regex patterns for better performance
		self._file_pattern = re.compile(r"diff --git a/.*? b/(.*?)\n")
		self._hunk_pattern = re.compile(r"@@ -\d+,\d+ \+\d+,\d+ @@")

	def split(self, diff: GitDiff) -> list[DiffChunk]:
		"""
		Split the diff into chunks.

		Args:
		    diff: GitDiff object to split

		Returns:
		    List of DiffChunk objects

		"""
		msg = "Subclasses must implement this method"
		raise NotImplementedError(msg)

__init__

__init__(
	embedding_model: EmbeddingModel | None = None,
) -> None

Initialize with optional embedding model.

Source code in src/codemap/git/diff_splitter/strategies.py

def __init__(self, embedding_model: EmbeddingModel | None = None) -> None:
	"""Initialize with optional embedding model."""
	self._embedding_model = embedding_model
	# Precompile regex patterns for better performance
	self._file_pattern = re.compile(r"diff --git a/.*? b/(.*?)\n")
	self._hunk_pattern = re.compile(r"@@ -\d+,\d+ \+\d+,\d+ @@")

split

split(diff: GitDiff) -> list[DiffChunk]

Split the diff into chunks.

Parameters:

Name	Type	Description	Default
diff	GitDiff	GitDiff object to split	required

Returns:

Type	Description
list[DiffChunk]	List of DiffChunk objects

Source code in src/codemap/git/diff_splitter/strategies.py

def split(self, diff: GitDiff) -> list[DiffChunk]:
	"""
	Split the diff into chunks.

	Args:
	    diff: GitDiff object to split

	Returns:
	    List of DiffChunk objects

	"""
	msg = "Subclasses must implement this method"
	raise NotImplementedError(msg)

FileSplitStrategy

Bases: BaseSplitStrategy

Strategy to split diffs by file.

Source code in src/codemap/git/diff_splitter/strategies.py

class FileSplitStrategy(BaseSplitStrategy):
	"""Strategy to split diffs by file."""

	def split(self, diff: GitDiff) -> list[DiffChunk]:
		"""
		Split a diff into chunks by file.

		Args:
		    diff: GitDiff object to split

		Returns:
		    List of DiffChunk objects, one per file

		"""
		if not diff.content:
			return self._handle_empty_diff_content(diff)

		# Split the diff content by file
		file_chunks = self._file_pattern.split(diff.content)[1:]  # Skip first empty chunk

		# Group files with their content
		chunks = []
		for i in range(0, len(file_chunks), 2):
			if i + 1 >= len(file_chunks):
				break

			file_name = file_chunks[i]
			content = file_chunks[i + 1]

			if self._is_valid_filename(file_name) and content:
				diff_header = f"diff --git a/{file_name} b/{file_name}\n"
				chunks.append(
					DiffChunk(
						files=[file_name],
						content=diff_header + content,
						description=f"Changes in {file_name}",
					)
				)

		return chunks

	def _handle_empty_diff_content(self, diff: GitDiff) -> list[DiffChunk]:
		"""Handle untracked files in empty diff content."""
		if (not diff.is_staged or diff.is_untracked) and diff.files:
			# Filter out invalid file names
			valid_files = [file for file in diff.files if self._is_valid_filename(file)]
			return [DiffChunk(files=[f], content="", description=f"New file: {f}") for f in valid_files]
		return []

	@staticmethod
	def _is_valid_filename(filename: str) -> bool:
		"""Check if the filename is valid (not a pattern or template)."""
		if not filename:
			return False
		invalid_chars = ["*", "+", "{", "}", "\\"]
		return not (any(char in filename for char in invalid_chars) or filename.startswith('"'))

split

split(diff: GitDiff) -> list[DiffChunk]

Split a diff into chunks by file.

Parameters:

Name	Type	Description	Default
diff	GitDiff	GitDiff object to split	required

Returns:

Type	Description
list[DiffChunk]	List of DiffChunk objects, one per file

Source code in src/codemap/git/diff_splitter/strategies.py

def split(self, diff: GitDiff) -> list[DiffChunk]:
	"""
	Split a diff into chunks by file.

	Args:
	    diff: GitDiff object to split

	Returns:
	    List of DiffChunk objects, one per file

	"""
	if not diff.content:
		return self._handle_empty_diff_content(diff)

	# Split the diff content by file
	file_chunks = self._file_pattern.split(diff.content)[1:]  # Skip first empty chunk

	# Group files with their content
	chunks = []
	for i in range(0, len(file_chunks), 2):
		if i + 1 >= len(file_chunks):
			break

		file_name = file_chunks[i]
		content = file_chunks[i + 1]

		if self._is_valid_filename(file_name) and content:
			diff_header = f"diff --git a/{file_name} b/{file_name}\n"
			chunks.append(
				DiffChunk(
					files=[file_name],
					content=diff_header + content,
					description=f"Changes in {file_name}",
				)
			)

	return chunks

SemanticSplitStrategy

Bases: BaseSplitStrategy

Strategy to split diffs semantically.

Source code in src/codemap/git/diff_splitter/strategies.py

class SemanticSplitStrategy(BaseSplitStrategy):
	"""Strategy to split diffs semantically."""

	def __init__(
		self,
		embedding_model: EmbeddingModel | None = None,
		code_extensions: set[str] | None = None,
		related_file_patterns: list[tuple[Pattern, Pattern]] | None = None,
		similarity_threshold: float = 0.4,
		directory_similarity_threshold: float = 0.3,
		min_chunks_for_consolidation: int = 2,
		max_chunks_before_consolidation: int = 20,
		max_file_size_for_llm: int | None = None,
	) -> None:
		"""
		Initialize the SemanticSplitStrategy.

		Args:
		    embedding_model: Optional embedding model instance
		    code_extensions: Optional set of code file extensions. Defaults to config.
		    related_file_patterns: Optional list of related file patterns
		    similarity_threshold: Threshold for grouping by content similarity.
		    directory_similarity_threshold: Threshold for directory similarity.
		    min_chunks_for_consolidation: Min chunks to trigger consolidation.
		    max_chunks_before_consolidation: Max chunks allowed before forced consolidation.
		    max_file_size_for_llm: Max file size for LLM processing.

		"""
		super().__init__(embedding_model)
		# Store thresholds and settings
		self.similarity_threshold = similarity_threshold
		self.directory_similarity_threshold = directory_similarity_threshold
		self.min_chunks_for_consolidation = min_chunks_for_consolidation
		self.max_chunks_before_consolidation = max_chunks_before_consolidation
		# Use default from config if not provided
		self.max_file_size_for_llm = (
			max_file_size_for_llm
			if max_file_size_for_llm is not None
			else DEFAULT_CONFIG["commit"]["diff_splitter"]["max_file_size_for_llm"]
		)

		# Set up file extensions, defaulting to config if None is passed
		self.code_extensions = (
			code_extensions
			if code_extensions is not None
			else set(DEFAULT_CONFIG["commit"]["diff_splitter"]["default_code_extensions"])
		)
		# Initialize patterns for related files
		self.related_file_patterns = related_file_patterns or self._initialize_related_file_patterns()

	def split(self, diff: GitDiff) -> list[DiffChunk]:
		"""
		Split a diff into chunks based on semantic relationships.

		Args:
		    diff: GitDiff object to split

		Returns:
		    List of DiffChunk objects based on semantic analysis

		"""
		if not diff.files:
			logger.debug("No files to process")
			return []

		# Validate embedding model is available
		self._validate_embedding_model()

		# Handle files in manageable groups
		if len(diff.files) > MAX_FILES_PER_GROUP:
			logger.info("Processing large number of files (%d) in smaller groups", len(diff.files))

			# Group files by directory to increase likelihood of related files being processed together
			files_by_dir = {}
			for file in diff.files:
				dir_path = str(Path(file).parent)
				if dir_path not in files_by_dir:
					files_by_dir[dir_path] = []
				files_by_dir[dir_path].append(file)

			# Process each directory group separately, keeping chunks under 5 files
			all_chunks = []
			# Iterate directly over the file lists since the directory path isn't used here
			for files in files_by_dir.values():
				# Process files in this directory in batches of 3-5
				for i in range(0, len(files), 3):
					batch = files[i : i + 3]
					# Create a new GitDiff for the batch, ensuring content is passed
					batch_diff = GitDiff(
						files=batch,
						content=diff.content,  # Pass the original full diff content
						is_staged=diff.is_staged,
					)
					all_chunks.extend(self._process_group(batch_diff))

			return all_chunks

		# For smaller groups, process normally
		return self._process_group(diff)

	def _process_group(self, diff: GitDiff) -> list[DiffChunk]:
		"""
		Process a GitDiff with one or more files.

		Originally designed for single files, but now supports multiple files.

		"""
		if not diff.files:
			logger.warning("_process_group called with empty files list")
			return []

		# If multiple files, this used to log an error, but now we'll handle it properly
		if len(diff.files) > 1:
			logger.debug("Processing group with multiple files: %s", diff.files)

			# Extract content for each file individually if possible
			chunks = []
			for file_path in diff.files:
				# Try to extract just this file's diff from the full content
				file_diff_content = self._extract_file_diff(diff.content, file_path)

				if file_diff_content:
					# Create a new diff for just this file
					file_diff = GitDiff(files=[file_path], content=file_diff_content, is_staged=diff.is_staged)
					# Process it and add the resulting chunks
					enhanced_chunks = self._enhance_semantic_split(file_diff)
					chunks.extend(enhanced_chunks)
				else:
					# If we couldn't extract just this file's diff, create a simple chunk
					chunks.append(
						DiffChunk(
							files=[file_path],
							content="",  # Empty content as we couldn't extract it
							description=f"Changes in {file_path}",
						)
					)

			# If we couldn't create any valid chunks, fallback to the original behavior
			if not chunks:
				return [DiffChunk(files=diff.files, content=diff.content, description="Multiple file changes")]

			return chunks

		# Original behavior for single file
		file_path = diff.files[0]

		# Enhance this single file diff
		enhanced_chunks = self._enhance_semantic_split(diff)  # Pass the original diff directly

		if not enhanced_chunks:
			logger.warning("No chunk generated for file: %s after enhancement.", file_path)
			# Fallback if enhancement yields nothing
			enhanced_chunks = [
				DiffChunk(
					files=[file_path],
					content=diff.content,
					description=f"Changes in {file_path} (enhancement failed)",
				)
			]

		# No further consolidation or grouping needed here as we process file-by-file now
		return enhanced_chunks

	def _extract_file_diff(self, full_diff_content: str, file_path: str) -> str:
		"""
		Extract the diff content for a specific file from a multi-file diff.

		Args:
		        full_diff_content: Complete diff content with multiple files
		        file_path: Path of the file to extract

		Returns:
		        The extracted diff for the specific file, or empty string if not found

		"""
		import re

		# Pattern to match the start of a diff for a file
		diff_start_pattern = re.compile(r"diff --git a/([^\s]+) b/([^\s]+)")

		# Find all diff start positions
		diff_positions = []
		for match in diff_start_pattern.finditer(full_diff_content):
			_, b_file = match.groups()
			# For most changes both files are the same; for renames prefer b_file
			target_file = b_file
			diff_positions.append((match.start(), target_file))

		# Sort by position
		diff_positions.sort()

		# Find the diff for our file
		file_diff = ""
		for i, (start_pos, diff_file) in enumerate(diff_positions):
			if diff_file == file_path:
				# Found our file, now find the end
				if i < len(diff_positions) - 1:
					end_pos = diff_positions[i + 1][0]
					file_diff = full_diff_content[start_pos:end_pos]
				else:
					# Last file in the diff
					file_diff = full_diff_content[start_pos:]
				break

		return file_diff

	def _validate_embedding_model(self) -> None:
		"""Validate that the embedding model is available."""
		if self._embedding_model is None and not is_test_environment():
			msg = (
				"Semantic analysis unavailable: embedding model not available. "
				"Make sure the model is properly loaded before calling this method."
			)
			raise ValueError(msg)

	def _group_chunks_by_directory(self, chunks: list[DiffChunk]) -> dict[str, list[DiffChunk]]:
		"""Group chunks by their containing directory."""
		dir_groups: dict[str, list[DiffChunk]] = {}

		for chunk in chunks:
			if not chunk.files:
				continue

			file_path = chunk.files[0]
			dir_path = file_path.rsplit("/", 1)[0] if "/" in file_path else "root"

			if dir_path not in dir_groups:
				dir_groups[dir_path] = []

			dir_groups[dir_path].append(chunk)

		return dir_groups

	def _process_directory_group(
		self, chunks: list[DiffChunk], processed_files: set[str], semantic_chunks: list[DiffChunk]
	) -> None:
		"""Process chunks in a single directory group."""
		if len(chunks) == 1:
			# If only one file in directory, add it directly
			semantic_chunks.append(chunks[0])
			if chunks[0].files:
				processed_files.update(chunks[0].files)
		else:
			# For directories with multiple files, try to group them
			dir_processed: set[str] = set()

			# First try to group by related file patterns
			self._group_related_files(chunks, dir_processed, semantic_chunks)

			# Then try to group remaining files by content similarity
			remaining_chunks = [c for c in chunks if not c.files or c.files[0] not in dir_processed]

			if remaining_chunks:
				# Use default similarity threshold instead
				self._group_by_content_similarity(remaining_chunks, semantic_chunks)

			# Add all processed files to the global processed set
			processed_files.update(dir_processed)

	def _process_remaining_chunks(
		self, all_chunks: list[DiffChunk], processed_files: set[str], semantic_chunks: list[DiffChunk]
	) -> None:
		"""Process any remaining chunks that weren't grouped by directory."""
		remaining_chunks = [c for c in all_chunks if c.files and c.files[0] not in processed_files]

		if remaining_chunks:
			self._group_by_content_similarity(remaining_chunks, semantic_chunks)

	def _consolidate_if_needed(self, semantic_chunks: list[DiffChunk]) -> list[DiffChunk]:
		"""Consolidate chunks if we have too many small ones."""
		has_single_file_chunks = any(len(chunk.files) == 1 for chunk in semantic_chunks)

		if len(semantic_chunks) > self.max_chunks_before_consolidation and has_single_file_chunks:
			return self._consolidate_small_chunks(semantic_chunks)

		return semantic_chunks

	@staticmethod
	def _initialize_related_file_patterns() -> list[tuple[Pattern, Pattern]]:
		"""
		Initialize and compile regex patterns for related files.

		Returns:
		    List of compiled regex pattern pairs

		"""
		# Pre-compile regex for efficiency and validation
		related_file_patterns = []
		# Define patterns using standard strings with escaped backreferences
		default_patterns: list[tuple[str, str]] = [
			# --- General Code + Test Files ---
			# Python
			("^(.*)\\.py$", "\\\\1_test\\.py$"),
			("^(.*)\\.py$", "test_\\\\1\\.py$"),
			("^(.*)\\.(py)$", "\\\\1_test\\.\\\\2$"),  # For file.py and file_test.py pattern
			("^(.*)\\.(py)$", "\\\\1Test\\.\\\\2$"),  # For file.py and fileTest.py pattern
			("^(.*)\\.py$", "\\\\1_spec\\.py$"),
			("^(.*)\\.py$", "spec_\\\\1\\.py$"),
			# JavaScript / TypeScript (including JSX/TSX)
			("^(.*)\\.(js|jsx|ts|tsx)$", "\\\\1\\.(test|spec)\\.(js|jsx|ts|tsx)$"),
			("^(.*)\\.(js|jsx|ts|tsx)$", "\\\\1\\.stories\\.(js|jsx|ts|tsx)$"),  # Storybook
			("^(.*)\\.(js|ts)$", "\\\\1\\.d\\.ts$"),  # JS/TS + Declaration files
			# Ruby
			("^(.*)\\.rb$", "\\\\1_spec\\.rb$"),
			("^(.*)\\.rb$", "\\\\1_test\\.rb$"),
			("^(.*)\\.rb$", "spec/.*_spec\\.rb$"),  # Common RSpec structure
			# Java
			("^(.*)\\.java$", "\\\\1Test\\.java$"),
			("src/main/java/(.*)\\.java$", "src/test/java/\\\\1Test\\.java$"),  # Maven/Gradle structure
			# Go
			("^(.*)\\.go$", "\\\\1_test\\.go$"),
			# C#
			("^(.*)\\.cs$", "\\\\1Tests?\\.cs$"),
			# PHP
			("^(.*)\\.php$", "\\\\1Test\\.php$"),
			("^(.*)\\.php$", "\\\\1Spec\\.php$"),
			("src/(.*)\\.php$", "tests/\\\\1Test\\.php$"),  # Common structure
			# Rust
			("src/(lib|main)\\.rs$", "tests/.*\\.rs$"),  # Main/Lib and integration tests
			("src/(.*)\\.rs$", "src/\\\\1_test\\.rs$"),  # Inline tests (less common for grouping)
			# Swift
			("^(.*)\\.swift$", "\\\\1Tests?\\.swift$"),
			# Kotlin
			("^(.*)\\.kt$", "\\\\1Test\\.kt$"),
			("src/main/kotlin/(.*)\\.kt$", "src/test/kotlin/\\\\1Test\\.kt$"),  # Common structure
			# --- Frontend Component Bundles ---
			# JS/TS Components + Styles (CSS, SCSS, LESS, CSS Modules)
			("^(.*)\\.(js|jsx|ts|tsx)$", "\\\\1\\.(css|scss|less)$"),
			("^(.*)\\.(js|jsx|ts|tsx)$", "\\\\1\\.module\\.(css|scss|less)$"),
			("^(.*)\\.(js|jsx|ts|tsx)$", "\\\\1\\.styles?\\.(js|ts)$"),  # Styled Components / Emotion convention
			# Vue Components + Styles
			("^(.*)\\.vue$", "\\\\1\\.(css|scss|less)$"),
			("^(.*)\\.vue$", "\\\\1\\.module\\.(css|scss|less)$"),
			# Svelte Components + Styles/Scripts
			("^(.*)\\.svelte$", "\\\\1\\.(css|scss|less)$"),
			("^(.*)\\.svelte$", "\\\\1\\.(js|ts)$"),
			# Angular Components (more specific structure)
			("^(.*)\\.component\\.ts$", "\\\\1\\.component\\.html$"),
			("^(.*)\\.component\\.ts$", "\\\\1\\.component\\.(css|scss|less)$"),
			("^(.*)\\.component\\.ts$", "\\\\1\\.component\\.spec\\.ts$"),  # Component + its test
			("^(.*)\\.service\\.ts$", "\\\\1\\.service\\.spec\\.ts$"),  # Service + its test
			("^(.*)\\.module\\.ts$", "\\\\1\\.routing\\.module\\.ts$"),  # Module + routing
			# --- Implementation / Definition / Generation ---
			# C / C++ / Objective-C
			("^(.*)\\.h$", "\\\\1\\.c$"),
			("^(.*)\\.h$", "\\\\1\\.m$"),
			("^(.*)\\.hpp$", "\\\\1\\.cpp$"),
			("^(.*)\\.h$", "\\\\1\\.cpp$"),  # Allow .h with .cpp
			("^(.*)\\.h$", "\\\\1\\.mm$"),
			# Protocol Buffers / gRPC
			("^(.*)\\.proto$", "\\\\1\\.pb\\.(go|py|js|java|rb|cs|ts)$"),
			("^(.*)\\.proto$", "\\\\1_pb2?\\.py$"),  # Python specific proto generation
			("^(.*)\\.proto$", "\\\\1_grpc\\.pb\\.(go|js|ts)$"),  # gRPC specific
			# Interface Definition Languages (IDL)
			("^(.*)\\.idl$", "\\\\1\\.(h|cpp|cs|java)$"),
			# API Specifications (OpenAPI/Swagger)
			("(openapi|swagger)\\.(yaml|yml|json)$", ".*\\.(go|py|js|java|rb|cs|ts)$"),  # Spec + generated code
			("^(.*)\\.(yaml|yml|json)$", "\\\\1\\.generated\\.(go|py|js|java|rb|cs|ts)$"),  # Another convention
			# --- Web Development (HTML Centric) ---
			("^(.*)\\.html$", "\\\\1\\.(js|ts)$"),
			("^(.*)\\.html$", "\\\\1\\.(css|scss|less)$"),
			# --- Mobile Development ---
			# iOS (Swift)
			("^(.*)\\.swift$", "\\\\1\\.storyboard$"),
			("^(.*)\\.swift$", "\\\\1\\.xib$"),
			# Android (Kotlin/Java)
			("^(.*)\\.(kt|java)$", "res/layout/.*\\.(xml)$"),  # Code + Layout XML (Path sensitive)
			("AndroidManifest\\.xml$", ".*\\.(kt|java)$"),  # Manifest + Code
			("build\\.gradle(\\.kts)?$", ".*\\.(kt|java)$"),  # Gradle build + Code
			# --- Configuration Files ---
			# Package Managers
			("package\\.json$", "(package-lock\\.json|yarn\\.lock|pnpm-lock\\.yaml)$"),
			("requirements\\.txt$", "(setup\\.py|setup\\.cfg|pyproject\\.toml)$"),
			("pyproject\\.toml$", "(setup\\.py|setup\\.cfg|poetry\\.lock|uv\\.lock)$"),
			("Gemfile$", "Gemfile\\.lock$"),
			("Cargo\\.toml$", "Cargo\\.lock$"),
			("composer\\.json$", "composer\\.lock$"),  # PHP Composer
			("go\\.mod$", "go\\.sum$"),  # Go Modules
			("pom\\.xml$", ".*\\.java$"),  # Maven + Java
			("build\\.gradle(\\.kts)?$", ".*\\.(java|kt)$"),  # Gradle + Java/Kotlin
			# Linters / Formatters / Compilers / Type Checkers
			(
				"package\\.json$",
				"(tsconfig\\.json|\\.eslintrc(\\..*)?|\\.prettierrc(\\..*)?|\\.babelrc(\\..*)?|webpack\\.config\\.js|vite\\.config\\.(js|ts))$",
			),
			("pyproject\\.toml$", "(\\.flake8|\\.pylintrc|\\.isort\\.cfg|mypy\\.ini)$"),
			# Docker
			("Dockerfile$", "(\\.dockerignore|docker-compose\\.yml)$"),
			("docker-compose\\.yml$", "\\.env$"),
			# CI/CD
			("\\.github/workflows/.*\\.yml$", ".*\\.(sh|py|js|ts|go)$"),  # Workflow + scripts
			("\\.gitlab-ci\\.yml$", ".*\\.(sh|py|js|ts|go)$"),
			("Jenkinsfile$", ".*\\.(groovy|sh|py)$"),
			# IaC (Terraform)
			("^(.*)\\.tf$", "\\\\1\\.tfvars$"),
			("^(.*)\\.tf$", "\\\\1\\.tf$"),  # Group TF files together
			# --- Documentation ---
			("README\\.md$", ".*$"),  # README often updated with any change
			("^(.*)\\.md$", "\\\\1\\.(py|js|ts|go|java|rb|rs|php|swift|kt)$"),  # Markdown doc + related code
			("docs/.*\\.md$", "src/.*$"),  # Documentation in docs/ related to src/
			# --- Data Science / ML ---
			("^(.*)\\.ipynb$", "\\\\1\\.py$"),  # Notebook + Python script
			("^(.*)\\.py$", "data/.*\\.(csv|json|parquet)$"),  # Script + Data file (path sensitive)
			# --- General Fallbacks (Use with caution) ---
			# Files with same base name but different extensions (already covered by some specifics)
			# ("^(.*)\\..*$", "\\1\\..*$"), # Potentially too broad, rely on specifics above
		]

		for pattern1_str, pattern2_str in default_patterns:
			try:
				# Compile with IGNORECASE for broader matching
				pattern1 = re.compile(pattern1_str, re.IGNORECASE)
				pattern2 = re.compile(pattern2_str, re.IGNORECASE)
				related_file_patterns.append((pattern1, pattern2))
			except re.error as e:
				# Log only if pattern compilation fails
				logger.warning(f"Failed to compile regex pair: ({pattern1_str!r}, {pattern2_str!r}). Error: {e}")

		return related_file_patterns

	def _get_code_embedding(self, content: str) -> list[float] | None:
		"""
		Get embedding vector for code content.

		Args:
		    content: Code content to embed

		Returns:
		    List of floats representing code embedding or None if unavailable

		"""
		# Skip empty content
		if not content or not content.strip():
			return None

		# Check if embedding model exists
		if self._embedding_model is None:
			logger.warning("Embedding model is None, cannot generate embedding")
			return None

		# Generate embedding with error handling
		try:
			embeddings = self._embedding_model.encode([content], show_progress_bar=False)
			# Check if the result is valid and has the expected structure
			if embeddings is not None and len(embeddings) > 0 and isinstance(embeddings[0], np.ndarray):
				return embeddings[0].tolist()
			logger.warning("Embedding model returned unexpected result type: %s", type(embeddings))
			return None
		except (ValueError, TypeError, RuntimeError, IndexError, AttributeError) as e:
			# Catch a broader range of potential exceptions during encode/toList
			logger.warning("Failed to generate embedding for content snippet: %s", e)
			return None
		except Exception:  # Catch any other unexpected errors
			logger.exception("Unexpected error during embedding generation")
			return None

	def _calculate_semantic_similarity(self, content1: str, content2: str) -> float:
		"""
		Calculate semantic similarity between two code chunks.

		Args:
		    content1: First code content
		    content2: Second code content

		Returns:
		    Similarity score between 0 and 1

		"""
		# Get embeddings
		emb1 = self._get_code_embedding(content1)
		emb2 = self._get_code_embedding(content2)

		if not emb1 or not emb2:
			return 0.0

		# Calculate cosine similarity using utility function
		return calculate_semantic_similarity(emb1, emb2)

	# --- New Helper Methods for Refactoring _enhance_semantic_split ---

	def _parse_file_diff(self, diff_content: str, file_path: str) -> PatchedFile | None:
		"""Parse diff content to find the PatchedFile for a specific file path."""
		if not diff_content:
			logger.warning("Cannot parse empty diff content for %s", file_path)
			return None

		filtered_content = ""  # Initialize to handle unbound case
		try:
			# Filter out the truncation marker lines before parsing
			filtered_content_lines = [
				line for line in diff_content.splitlines() if line.strip() != "... [content truncated] ..."
			]
			filtered_content = "\n".join(filtered_content_lines)

			# Use StringIO as PatchSet expects a file-like object or iterable
			try:
				patch_set = PatchSet(StringIO(filtered_content))
			except UnidiffParseError as e:
				logger.warning("UnidiffParseError for %s: %s", file_path, str(e))
				# Try to extract just the diff for this specific file to avoid parsing the entire diff
				file_diff_content_raw = re.search(
					rf"diff --git a/.*? b/{re.escape(file_path)}\n(.*?)(?=diff --git a/|\Z)",
					diff_content,
					re.DOTALL | re.MULTILINE,
				)
				content_for_chunk = file_diff_content_raw.group(0) if file_diff_content_raw else ""
				if content_for_chunk:
					logger.debug("Extracted raw content for %s after parse error", file_path)
					# Create a manual PatchedFile since we can't parse it properly
					return None
				return None

			matched_file: PatchedFile | None = None
			for patched_file in patch_set:
				# unidiff paths usually start with a/ or b/
				if patched_file.target_file == f"b/{file_path}" or patched_file.path == file_path:
					matched_file = patched_file
					break
			if not matched_file:
				logger.warning("Could not find matching PatchedFile for: %s in unidiff output", file_path)
				return None
			return matched_file
		except UnidiffParseError:
			# Log the specific parse error and the content that caused it (first few lines)
			preview_lines = "\n".join(filtered_content.splitlines()[:10])  # Log first 10 lines
			logger.exception(
				"UnidiffParseError for %s\nContent Preview:\n%s",  # Corrected format string
				file_path,
				preview_lines,
			)
			return None  # Return None on parse error
		except Exception:
			logger.exception("Failed to parse diff content using unidiff for %s", file_path)
			return None

	def _reconstruct_file_diff(self, patched_file: PatchedFile) -> tuple[str, str]:
		"""Reconstruct the diff header and full diff content for a PatchedFile."""
		file_diff_hunks_content = "\n".join(str(hunk) for hunk in patched_file)
		file_header_obj = getattr(patched_file, "patch_info", None)
		file_header = str(file_header_obj) if file_header_obj else ""

		if not file_header.startswith("diff --git") and patched_file.source_file and patched_file.target_file:
			logger.debug("Reconstructing missing diff header for %s", patched_file.path)
			file_header = f"diff --git {patched_file.source_file} {patched_file.target_file}\n"
			if hasattr(patched_file, "index") and patched_file.index:
				file_header += f"index {patched_file.index}\n"
			# Use timestamps if available for more accurate header reconstruction
			source_ts = f"\t{patched_file.source_timestamp}" if patched_file.source_timestamp else ""
			target_ts = f"\t{patched_file.target_timestamp}" if patched_file.target_timestamp else ""
			file_header += f"--- {patched_file.source_file}{source_ts}\n"
			file_header += f"+++ {patched_file.target_file}{target_ts}\n"

		full_file_diff_content = file_header + file_diff_hunks_content
		return file_header, full_file_diff_content

	def _split_large_file_diff(self, patched_file: PatchedFile, file_header: str) -> list[DiffChunk]:
		"""Split a large file's diff by grouping hunks under the size limit."""
		file_path = patched_file.path
		max_chunk_size = self.max_file_size_for_llm  # Use instance config
		logger.info(
			"Splitting large file diff for %s by hunks (limit: %d bytes)",
			file_path,
			max_chunk_size,
		)
		large_file_chunks = []
		current_hunk_group: list[Hunk] = []
		current_group_size = len(file_header)  # Start with header size

		for hunk in patched_file:
			hunk_content_str = str(hunk)
			hunk_size = len(hunk_content_str) + 1  # +1 for newline separator

			# If adding this hunk exceeds the limit (and group isn't empty), finalize the current chunk
			if current_hunk_group and current_group_size + hunk_size > max_chunk_size:
				group_content = file_header + "\n".join(str(h) for h in current_hunk_group)
				description = f"Chunk {len(large_file_chunks) + 1} of large file {file_path}"
				large_file_chunks.append(DiffChunk(files=[file_path], content=group_content, description=description))
				# Start a new chunk with the current hunk
				current_hunk_group = [hunk]
				current_group_size = len(file_header) + hunk_size
			# Edge case: If a single hunk itself is too large, create a chunk just for it
			elif not current_hunk_group and len(file_header) + hunk_size > max_chunk_size:
				logger.warning(
					"Single hunk in %s exceeds size limit (%d bytes). Creating oversized chunk.",
					file_path,
					len(file_header) + hunk_size,
				)
				group_content = file_header + hunk_content_str
				description = f"Chunk {len(large_file_chunks) + 1} (oversized hunk) of large file {file_path}"
				large_file_chunks.append(DiffChunk(files=[file_path], content=group_content, description=description))
				# Reset for next potential chunk (don't carry this huge hunk forward)
				current_hunk_group = []
				current_group_size = len(file_header)
			else:
				# Add hunk to the current group
				current_hunk_group.append(hunk)
				current_group_size += hunk_size

		# Add the last remaining chunk group if any
		if current_hunk_group:
			group_content = file_header + "\n".join(str(h) for h in current_hunk_group)
			description = f"Chunk {len(large_file_chunks) + 1} of large file {file_path}"
			large_file_chunks.append(DiffChunk(files=[file_path], content=group_content, description=description))

		return large_file_chunks

	# --- Refactored Orchestrator Method ---

	def _enhance_semantic_split(self, diff: GitDiff) -> list[DiffChunk]:
		"""
		Enhance the semantic split by using NLP and chunk detection.

		Args:
		    diff: The GitDiff object to split

		Returns:
		    List of enhanced DiffChunk objects

		"""
		if not diff.files:
			return []

		# Special handling for untracked files - avoid unidiff parsing errors
		if diff.is_untracked:
			# Create a basic chunk with only file info for untracked files
			# Use a list comprehension for performance (PERF401)
			return [
				DiffChunk(
					files=[file_path],
					content=diff.content if len(diff.files) == 1 else f"New untracked file: {file_path}",
					description=f"New file: {file_path}",
				)
				for file_path in diff.files
				if self._is_valid_filename(file_path)
			]

		if not diff.files or len(diff.files) != 1:
			logger.error("_enhance_semantic_split called with invalid diff object (files=%s)", diff.files)
			return []

		file_path = diff.files[0]
		extension = Path(file_path).suffix[1:].lower()

		if not diff.content:
			logger.warning("No diff content provided for %s, creating basic chunk.", file_path)
			return [DiffChunk(files=[file_path], content="", description=f"New file: {file_path}")]

		# 1. Parse the diff to get the PatchedFile object
		matched_file = self._parse_file_diff(diff.content, file_path)
		if not matched_file:
			# If parsing failed, return a basic chunk with raw content attempt
			file_diff_content_raw = re.search(
				rf"diff --git a/.*? b/{re.escape(file_path)}\n(.*?)(?=diff --git a/|\Z)",
				diff.content,
				re.DOTALL | re.MULTILINE,
			)
			content_for_chunk = file_diff_content_raw.group(0) if file_diff_content_raw else ""
			return [
				DiffChunk(
					files=[file_path],
					content=content_for_chunk,
					description=f"Changes in {file_path} (parsing failed)",
				)
			]

		# 2. Reconstruct the full diff content for this file
		file_header, full_file_diff_content = self._reconstruct_file_diff(matched_file)

		# 3. Check if the reconstructed diff is too large
		if len(full_file_diff_content) > self.max_file_size_for_llm:
			return self._split_large_file_diff(matched_file, file_header)

		# 4. Try splitting by semantic patterns (if applicable)
		patterns = get_language_specific_patterns(extension)
		if patterns:
			logger.debug("Attempting semantic pattern splitting for %s", file_path)
			pattern_chunks = self._split_by_semantic_patterns(matched_file, patterns)
			if pattern_chunks:
				return pattern_chunks
			logger.debug("Pattern splitting yielded no chunks for %s, falling back.", file_path)

		# 5. Fallback: Split by individual hunks
		logger.debug("Falling back to hunk splitting for %s", file_path)
		hunk_chunks = []
		for hunk in matched_file:
			hunk_content = str(hunk)
			hunk_chunks.append(
				DiffChunk(
					files=[file_path],
					content=file_header + hunk_content,  # Combine header + hunk
					description=f"Hunk in {file_path} starting near line {hunk.target_start}",
				)
			)

		# If no hunks were found at all, return the single reconstructed chunk
		if not hunk_chunks:
			logger.warning("No hunks detected for %s after parsing, returning full diff.", file_path)
			return [
				DiffChunk(
					files=[file_path],
					content=full_file_diff_content,
					description=f"Changes in {file_path} (no hunks detected)",
				)
			]

		return hunk_chunks

	# --- Existing Helper Methods (Potentially need review/updates) ---

	def _group_by_content_similarity(
		self,
		chunks: list[DiffChunk],
		result_chunks: list[DiffChunk],
		similarity_threshold: float | None = None,
	) -> None:
		"""
		Group chunks by content similarity.

		Args:
		    chunks: List of chunks to process
		    result_chunks: List to append grouped chunks to (modified in place)
		    similarity_threshold: Optional custom threshold to override default

		"""
		if not chunks:
			return

		# Check if model is available
		if self._embedding_model is None:
			logger.debug("Embedding model not available, using fallback grouping strategy")
			# If model is unavailable, try to group by file path patterns
			grouped_paths: dict[str, list[DiffChunk]] = {}

			# Group by common path prefixes
			for chunk in chunks:
				if not chunk.files:
					result_chunks.append(chunk)
					continue

				file_path = chunk.files[0]
				# Get directory or file prefix as the grouping key
				if "/" in file_path:
					# Use directory as key
					key = file_path.rsplit("/", 1)[0]
				else:
					# Use file prefix (before extension) as key
					key = file_path.split(".", 1)[0] if "." in file_path else file_path

				if key not in grouped_paths:
					grouped_paths[key] = []
				grouped_paths[key].append(chunk)

			# Create chunks from each group
			for related_chunks in grouped_paths.values():
				self._create_semantic_chunk(related_chunks, result_chunks)
			return

		processed_indices = set()
		threshold = similarity_threshold if similarity_threshold is not None else self.similarity_threshold

		# For each chunk, find similar chunks and group them
		for i, chunk in enumerate(chunks):
			if i in processed_indices:
				continue

			related_chunks = [chunk]
			processed_indices.add(i)

			# Find similar chunks
			for j, other_chunk in enumerate(chunks):
				if i == j or j in processed_indices:
					continue

				# Calculate similarity between chunks
				similarity = self._calculate_semantic_similarity(chunk.content, other_chunk.content)

				if similarity >= threshold:
					related_chunks.append(other_chunk)
					processed_indices.add(j)

			# Create a semantic chunk from related chunks
			if related_chunks:
				self._create_semantic_chunk(related_chunks, result_chunks)

	def _group_related_files(
		self,
		file_chunks: list[DiffChunk],
		processed_files: set[str],
		semantic_chunks: list[DiffChunk],
	) -> None:
		"""
		Group related files into semantic chunks.

		Args:
		    file_chunks: List of file-based chunks
		    processed_files: Set of already processed files (modified in place)
		    semantic_chunks: List of semantic chunks (modified in place)

		"""
		if not file_chunks:
			return

		# Group clearly related files
		for i, chunk in enumerate(file_chunks):
			if not chunk.files or chunk.files[0] in processed_files:
				continue

			related_chunks = [chunk]
			processed_files.add(chunk.files[0])

			# Find related files
			for j, other_chunk in enumerate(file_chunks):
				if i == j or not other_chunk.files or other_chunk.files[0] in processed_files:
					continue

				if are_files_related(chunk.files[0], other_chunk.files[0], self.related_file_patterns):
					related_chunks.append(other_chunk)
					processed_files.add(other_chunk.files[0])

			# Create a semantic chunk from related files
			if related_chunks:
				self._create_semantic_chunk(related_chunks, semantic_chunks)

	def _create_semantic_chunk(
		self,
		related_chunks: list[DiffChunk],
		semantic_chunks: list[DiffChunk],
	) -> None:
		"""
		Create a semantic chunk from related file chunks.

		Args:
		    related_chunks: List of related file chunks
		    semantic_chunks: List of semantic chunks to append to (modified in place)

		"""
		if not related_chunks:
			return

		all_files = []
		combined_content = []

		for rc in related_chunks:
			all_files.extend(rc.files)
			combined_content.append(rc.content)

		# Determine the appropriate commit type based on the files
		commit_type = determine_commit_type(all_files)

		# Create description based on file count
		description = create_chunk_description(commit_type, all_files)

		# Join the content from all related chunks
		content = "\n\n".join(combined_content)

		semantic_chunks.append(
			DiffChunk(
				files=all_files,
				content=content,
				description=description,
			)
		)

	def _should_merge_chunks(self, chunk1: DiffChunk, chunk2: DiffChunk) -> bool:
		"""Determine if two chunks should be merged."""
		# Condition 1: Same single file
		same_file = len(chunk1.files) == 1 and chunk1.files == chunk2.files

		# Condition 2: Related single files
		related_files = (
			len(chunk1.files) == 1
			and len(chunk2.files) == 1
			and are_files_related(chunk1.files[0], chunk2.files[0], self.related_file_patterns)
		)

		# Return True if either condition is met
		return same_file or related_files

	def _consolidate_small_chunks(self, initial_chunks: list[DiffChunk]) -> list[DiffChunk]:
		"""
		Merge small or related chunks together.

		First, consolidates chunks originating from the same file.
		Then, consolidates remaining single-file chunks by directory.

		Args:
		    initial_chunks: List of diff chunks to consolidate

		Returns:
		    Consolidated list of chunks

		"""
		# Use instance variable for threshold
		if len(initial_chunks) < self.min_chunks_for_consolidation:
			return initial_chunks

		# Consolidate small chunks for the same file or related files
		consolidated_chunks = []
		processed_indices = set()

		for i, chunk1 in enumerate(initial_chunks):
			if i in processed_indices:
				continue

			merged_chunk = chunk1
			processed_indices.add(i)

			# Check subsequent chunks for merging
			for j in range(i + 1, len(initial_chunks)):
				if j in processed_indices:
					continue

				chunk2 = initial_chunks[j]

				# Check if chunks should be merged (same file or related)
				if self._should_merge_chunks(merged_chunk, chunk2):
					# Combine files if merging related chunks, not just same file chunks
					new_files = merged_chunk.files
					if (
						len(merged_chunk.files) == 1
						and len(chunk2.files) == 1
						and merged_chunk.files[0] != chunk2.files[0]
					):
						new_files = sorted(set(merged_chunk.files + chunk2.files))

					# Merge content and potentially other attributes
					# Ensure a newline between merged content if needed
					separator = "\n" if merged_chunk.content and chunk2.content else ""
					merged_chunk = dataclasses.replace(
						merged_chunk,
						files=new_files,
						content=merged_chunk.content + separator + chunk2.content,
						description=merged_chunk.description,  # Keep first description
					)
					processed_indices.add(j)

			consolidated_chunks.append(merged_chunk)

		return consolidated_chunks

	def _split_by_semantic_patterns(self, patched_file: PatchedFile, patterns: list[str]) -> list[DiffChunk]:
		"""
		Split a PatchedFile's content by grouping hunks based on semantic patterns.

		This method groups consecutive hunks together until a hunk is encountered
		that contains an added line matching one of the semantic boundary patterns.
		It does *not* split within a single hunk, only between hunks where a boundary
		is detected in the *first* line of the subsequent hunk group.

		Args:
		    patched_file: The PatchedFile object from unidiff.
		    patterns: List of regex pattern strings to match as boundaries.

		Returns:
		    List of DiffChunk objects, potentially splitting the file into multiple chunks.

		"""
		compiled_patterns = [re.compile(p) for p in patterns]
		file_path = patched_file.path  # Or target_file? Need consistency

		final_chunks_data: list[list[Hunk]] = []
		current_semantic_chunk_hunks: list[Hunk] = []

		# Get header info once using the reconstruction helper
		file_header, _ = self._reconstruct_file_diff(patched_file)

		for hunk in patched_file:
			hunk_has_boundary = False
			for line in hunk:
				if line.is_added and any(pattern.match(line.value) for pattern in compiled_patterns):
					hunk_has_boundary = True
					break  # Found a boundary in this hunk

			# Start a new semantic chunk if the current hunk has a boundary
			# and we already have hunks accumulated.
			if hunk_has_boundary and current_semantic_chunk_hunks:
				final_chunks_data.append(current_semantic_chunk_hunks)
				current_semantic_chunk_hunks = [hunk]  # Start new chunk with this hunk
			else:
				# Append the current hunk to the ongoing semantic chunk
				current_semantic_chunk_hunks.append(hunk)

		# Add the last accumulated semantic chunk
		if current_semantic_chunk_hunks:
			final_chunks_data.append(current_semantic_chunk_hunks)

		# Convert grouped hunks into DiffChunk objects
		result_chunks: list[DiffChunk] = []
		for i, hunk_group in enumerate(final_chunks_data):
			if not hunk_group:
				continue
			# Combine content of all hunks in the group
			group_content = "\n".join(str(h) for h in hunk_group)
			# Generate description (could be more sophisticated)
			description = f"Semantic section {i + 1} in {file_path}"
			result_chunks.append(
				DiffChunk(
					files=[file_path],
					content=file_header + group_content,  # Combine header + hunks
					description=description,
				)
			)

		logger.debug("Split %s into %d chunks based on semantic patterns", file_path, len(result_chunks))
		return result_chunks

	@staticmethod
	def _is_valid_filename(filename: str) -> bool:
		"""Check if the filename is valid (not a pattern or template)."""
		if not filename:
			return False
		invalid_chars = ["*", "+", "{", "}", "\\"]
		return not (any(char in filename for char in invalid_chars) or filename.startswith('"'))

__init__

__init__(
	embedding_model: EmbeddingModel | None = None,
	code_extensions: set[str] | None = None,
	related_file_patterns: list[tuple[Pattern, Pattern]]
	| None = None,
	similarity_threshold: float = 0.4,
	directory_similarity_threshold: float = 0.3,
	min_chunks_for_consolidation: int = 2,
	max_chunks_before_consolidation: int = 20,
	max_file_size_for_llm: int | None = None,
) -> None

Initialize the SemanticSplitStrategy.

Parameters:

Name	Type	Description	Default
embedding_model	EmbeddingModel | None	Optional embedding model instance	None
code_extensions	set[str] | None	Optional set of code file extensions. Defaults to config.	None
related_file_patterns	list[tuple[Pattern, Pattern]] | None	Optional list of related file patterns	None
similarity_threshold	float	Threshold for grouping by content similarity.	0.4
directory_similarity_threshold	float	Threshold for directory similarity.	0.3
min_chunks_for_consolidation	int	Min chunks to trigger consolidation.	2
max_chunks_before_consolidation	int	Max chunks allowed before forced consolidation.	20
max_file_size_for_llm	int | None	Max file size for LLM processing.	None

Source code in src/codemap/git/diff_splitter/strategies.py

def __init__(
	self,
	embedding_model: EmbeddingModel | None = None,
	code_extensions: set[str] | None = None,
	related_file_patterns: list[tuple[Pattern, Pattern]] | None = None,
	similarity_threshold: float = 0.4,
	directory_similarity_threshold: float = 0.3,
	min_chunks_for_consolidation: int = 2,
	max_chunks_before_consolidation: int = 20,
	max_file_size_for_llm: int | None = None,
) -> None:
	"""
	Initialize the SemanticSplitStrategy.

	Args:
	    embedding_model: Optional embedding model instance
	    code_extensions: Optional set of code file extensions. Defaults to config.
	    related_file_patterns: Optional list of related file patterns
	    similarity_threshold: Threshold for grouping by content similarity.
	    directory_similarity_threshold: Threshold for directory similarity.
	    min_chunks_for_consolidation: Min chunks to trigger consolidation.
	    max_chunks_before_consolidation: Max chunks allowed before forced consolidation.
	    max_file_size_for_llm: Max file size for LLM processing.

	"""
	super().__init__(embedding_model)
	# Store thresholds and settings
	self.similarity_threshold = similarity_threshold
	self.directory_similarity_threshold = directory_similarity_threshold
	self.min_chunks_for_consolidation = min_chunks_for_consolidation
	self.max_chunks_before_consolidation = max_chunks_before_consolidation
	# Use default from config if not provided
	self.max_file_size_for_llm = (
		max_file_size_for_llm
		if max_file_size_for_llm is not None
		else DEFAULT_CONFIG["commit"]["diff_splitter"]["max_file_size_for_llm"]
	)

	# Set up file extensions, defaulting to config if None is passed
	self.code_extensions = (
		code_extensions
		if code_extensions is not None
		else set(DEFAULT_CONFIG["commit"]["diff_splitter"]["default_code_extensions"])
	)
	# Initialize patterns for related files
	self.related_file_patterns = related_file_patterns or self._initialize_related_file_patterns()

similarity_threshold instance-attribute

similarity_threshold = similarity_threshold

directory_similarity_threshold instance-attribute

directory_similarity_threshold = (
	directory_similarity_threshold
)

min_chunks_for_consolidation instance-attribute

min_chunks_for_consolidation = min_chunks_for_consolidation

max_chunks_before_consolidation instance-attribute

max_chunks_before_consolidation = (
	max_chunks_before_consolidation
)

max_file_size_for_llm instance-attribute

max_file_size_for_llm = (
	max_file_size_for_llm
	if max_file_size_for_llm is not None
	else DEFAULT_CONFIG["commit"]["diff_splitter"][
		"max_file_size_for_llm"
	]
)

code_extensions instance-attribute

code_extensions = (
	code_extensions
	if code_extensions is not None
	else set(
		DEFAULT_CONFIG["commit"]["diff_splitter"][
			"default_code_extensions"
		]
	)
)

related_file_patterns instance-attribute

related_file_patterns = (
	related_file_patterns
	or _initialize_related_file_patterns()
)

split

split(diff: GitDiff) -> list[DiffChunk]

Split a diff into chunks based on semantic relationships.

Parameters:

Name	Type	Description	Default
diff	GitDiff	GitDiff object to split	required

Returns:

Type	Description
list[DiffChunk]	List of DiffChunk objects based on semantic analysis

Source code in src/codemap/git/diff_splitter/strategies.py

def split(self, diff: GitDiff) -> list[DiffChunk]:
	"""
	Split a diff into chunks based on semantic relationships.

	Args:
	    diff: GitDiff object to split

	Returns:
	    List of DiffChunk objects based on semantic analysis

	"""
	if not diff.files:
		logger.debug("No files to process")
		return []

	# Validate embedding model is available
	self._validate_embedding_model()

	# Handle files in manageable groups
	if len(diff.files) > MAX_FILES_PER_GROUP:
		logger.info("Processing large number of files (%d) in smaller groups", len(diff.files))

		# Group files by directory to increase likelihood of related files being processed together
		files_by_dir = {}
		for file in diff.files:
			dir_path = str(Path(file).parent)
			if dir_path not in files_by_dir:
				files_by_dir[dir_path] = []
			files_by_dir[dir_path].append(file)

		# Process each directory group separately, keeping chunks under 5 files
		all_chunks = []
		# Iterate directly over the file lists since the directory path isn't used here
		for files in files_by_dir.values():
			# Process files in this directory in batches of 3-5
			for i in range(0, len(files), 3):
				batch = files[i : i + 3]
				# Create a new GitDiff for the batch, ensuring content is passed
				batch_diff = GitDiff(
					files=batch,
					content=diff.content,  # Pass the original full diff content
					is_staged=diff.is_staged,
				)
				all_chunks.extend(self._process_group(batch_diff))

		return all_chunks

	# For smaller groups, process normally
	return self._process_group(diff)

commit_generator

Commit message generation package for CodeMap.

This package provides modules for generating commit messages using LLMs.

DiffChunk dataclass

Represents a logical chunk of changes.

Source code in src/codemap/git/diff_splitter/schemas.py

@dataclass
class DiffChunk:
	"""Represents a logical chunk of changes."""

	files: list[str]
	content: str
	description: str | None = None
	is_llm_generated: bool = False
	filtered_files: list[str] | None = None

	def __post_init__(self) -> None:
		"""Initialize default values."""
		if self.filtered_files is None:
			self.filtered_files = []

	def __hash__(self) -> int:
		"""
		Make DiffChunk hashable by using the object's id.

		Returns:
		        Hash value based on the object's id

		"""
		return hash(id(self))

	def __eq__(self, other: object) -> bool:
		"""
		Compare DiffChunk objects for equality.

		Args:
		        other: Another object to compare with

		Returns:
		        True if the objects are the same instance, False otherwise

		"""
		if not isinstance(other, DiffChunk):
			return False
		return id(self) == id(other)

files instance-attribute

files: list[str]

content instance-attribute

content: str

description class-attribute instance-attribute

description: str | None = None

is_llm_generated class-attribute instance-attribute

is_llm_generated: bool = False

filtered_files class-attribute instance-attribute

filtered_files: list[str] | None = None

__post_init__

__post_init__() -> None

Initialize default values.

Source code in src/codemap/git/diff_splitter/schemas.py

def __post_init__(self) -> None:
	"""Initialize default values."""
	if self.filtered_files is None:
		self.filtered_files = []

__hash__

__hash__() -> int

Make DiffChunk hashable by using the object's id.

Returns:

Type	Description
int	Hash value based on the object's id

Source code in src/codemap/git/diff_splitter/schemas.py

def __hash__(self) -> int:
	"""
	Make DiffChunk hashable by using the object's id.

	Returns:
	        Hash value based on the object's id

	"""
	return hash(id(self))

__eq__

__eq__(other: object) -> bool

Compare DiffChunk objects for equality.

Parameters:

Name	Type	Description	Default
other	object	Another object to compare with	required

Returns:

Type	Description
bool	True if the objects are the same instance, False otherwise

Source code in src/codemap/git/diff_splitter/schemas.py

def __eq__(self, other: object) -> bool:
	"""
	Compare DiffChunk objects for equality.

	Args:
	        other: Another object to compare with

	Returns:
	        True if the objects are the same instance, False otherwise

	"""
	if not isinstance(other, DiffChunk):
		return False
	return id(self) == id(other)

__init__

__init__(
	files: list[str],
	content: str,
	description: str | None = None,
	is_llm_generated: bool = False,
	filtered_files: list[str] | None = None,
) -> None

CommitMessageGenerator

Generates commit messages using LLMs.

Source code in src/codemap/git/commit_generator/generator.py

class CommitMessageGenerator:
	"""Generates commit messages using LLMs."""

	def __init__(
		self,
		repo_root: Path,
		llm_client: LLMClient,
		prompt_template: str,
		config_loader: ConfigLoader,
	) -> None:
		"""
		Initialize the commit message generator.

		Args:
		    repo_root: Root directory of the Git repository
		    llm_client: LLMClient instance to use
		    prompt_template: Custom prompt template to use
		    config_loader: ConfigLoader instance to use for configuration

		"""
		self.repo_root = repo_root
		self.prompt_template = prompt_template
		self._config_loader = config_loader
		self.client = llm_client

		# Add commit template to client
		self.client.set_template("commit", self.prompt_template)

		# Get max token limit from config
		llm_config = self._config_loader.get("llm", {})
		self.max_tokens = llm_config.get("max_context_tokens", 4000)

		# Flag to control whether to use the LOD-based context processing
		self.use_lod_context = llm_config.get("use_lod_context", True)

	def extract_file_info(self, chunk: DiffChunk) -> dict[str, Any]:
		"""
		Extract file information from the diff chunk.

		Args:
		    chunk: Diff chunk object to extract information from

		Returns:
		    Dictionary with information about files

		"""
		file_info = {}
		files = chunk.files
		for file in files:
			if not isinstance(file, str):
				continue  # Skip non-string file entries
			file_path = self.repo_root / file
			if not file_path.exists():
				continue
			try:
				extension = file_path.suffix.lstrip(".")
				file_info[file] = {
					"extension": extension,
					"directory": str(file_path.parent.relative_to(self.repo_root)),
				}
				path_parts = file_path.parts
				if len(path_parts) > 1:
					if "src" in path_parts:
						idx = path_parts.index("src")
						if idx + 1 < len(path_parts):
							file_info[file]["module"] = path_parts[idx + 1]
					elif "tests" in path_parts:
						file_info[file]["module"] = "tests"
			except (ValueError, IndexError, TypeError):
				continue
		return file_info

	def get_commit_convention(self) -> dict[str, Any]:
		"""Get commit convention settings from config."""
		# Use the centralized ConfigLoader to get the convention
		return self._config_loader.get_commit_convention()

	def _prepare_prompt(self, chunk: DiffChunk) -> str:
		"""
		Prepare the prompt for the LLM.

		Args:
		    chunk: Diff chunk object to prepare prompt for

		Returns:
		    Prepared prompt with diff and file information

		"""
		file_info = self.extract_file_info(chunk)
		convention = self.get_commit_convention()

		# Get the diff content
		diff_content = chunk.content

		# Use the LOD-based context processor if enabled
		if self.use_lod_context:
			logger.debug("Using LOD-based context processing")
			try:
				# Process the chunk with LOD to optimize context length
				enhanced_diff_content = process_chunks_with_lod([chunk], self.max_tokens)

				if enhanced_diff_content:
					diff_content = enhanced_diff_content
					logger.debug("LOD context processing successful")
				else:
					logger.debug("LOD processing returned empty result, using original content")
			except Exception:
				logger.exception("Error during LOD context processing")
				# Continue with the original content if LOD processing fails
		else:
			# Use the original binary file detection logic
			binary_files = []
			for file_path in chunk.files:
				if file_path in file_info:
					extension = file_info[file_path].get("extension", "").lower()
					# Common binary file extensions
					binary_extensions = {
						"png",
						"jpg",
						"jpeg",
						"gif",
						"bmp",
						"tiff",
						"ico",
						"webp",  # Images
						"mp3",
						"wav",
						"ogg",
						"flac",
						"aac",  # Audio
						"mp4",
						"avi",
						"mkv",
						"mov",
						"webm",  # Video
						"pdf",
						"doc",
						"docx",
						"xls",
						"xlsx",
						"ppt",
						"pptx",  # Documents
						"zip",
						"tar",
						"gz",
						"rar",
						"7z",  # Archives
						"exe",
						"dll",
						"so",
						"dylib",  # Binaries
						"ttf",
						"otf",
						"woff",
						"woff2",  # Fonts
						"db",
						"sqlite",
						"mdb",  # Databases
					}

					if extension in binary_extensions:
						binary_files.append(file_path)

				# For absolute paths, try to check if the file is binary
				abs_path = self.repo_root / file_path
				try:
					if abs_path.exists():
						from codemap.utils.file_utils import is_binary_file

						if is_binary_file(abs_path) and file_path not in binary_files:
							binary_files.append(file_path)
				except (OSError, PermissionError) as e:
					# If any error occurs during binary check, log it and continue
					logger.debug("Error checking if %s is binary: %s", file_path, str(e))

			# If we have binary files or no diff content, enhance the prompt
			enhanced_diff_content = diff_content
			if not diff_content or binary_files:
				# Create a specialized header for binary files
				binary_files_header = ""
				if binary_files:
					binary_files_header = "BINARY FILES DETECTED:\n"
					for binary_file in binary_files:
						extension = file_info.get(binary_file, {}).get("extension", "unknown")
						binary_files_header += f"- {binary_file} (binary {extension} file)\n"
					binary_files_header += "\n"

				# If no diff content, create a more informative message about binary files
				if not diff_content:
					file_descriptions = []
					for file_path in chunk.files:
						if file_path in binary_files:
							extension = file_info.get(file_path, {}).get("extension", "unknown")
							file_descriptions.append(f"{file_path} (binary {extension} file)")
						else:
							extension = file_info.get(file_path, {}).get("extension", "")
							file_descriptions.append(f"{file_path} ({extension} file)")

					enhanced_diff_content = (
						f"{binary_files_header}This chunk contains changes to the following files "
						f"with no visible diff content (likely binary changes):\n"
					)
					for desc in file_descriptions:
						enhanced_diff_content += f"- {desc}\n"
				else:
					# If there is diff content but also binary files, add the binary files header
					enhanced_diff_content = binary_files_header + diff_content

			diff_content = enhanced_diff_content

		# Create a context dict with default values for template variables
		context = {
			"diff": diff_content,
			"files": file_info,
			"convention": convention,
			"schema": COMMIT_MESSAGE_SCHEMA,
			"original_message": "",  # Default value for original_message
			"lint_errors": "",  # Default value for lint_errors
		}

		# Prepare and return the prompt
		return prepare_prompt(
			template=self.prompt_template,
			diff_content=diff_content,
			file_info=file_info,
			convention=convention,
			extra_context=context,  # Pass the context with default values
		)

	def format_json_to_commit_message(self, content: str) -> str:
		"""
		Format a JSON string as a conventional commit message.

		Args:
		    content: JSON content string from LLM response

		Returns:
		    Formatted commit message string

		"""

		def _raise_validation_error(message: str) -> None:
			"""Helper to raise ValueError with consistent message."""
			logger.warning("LLM response validation failed: %s", message)
			msg = message
			raise ValueError(msg)

		try:
			# Try to parse the content as JSON
			debug_content = (
				content[:MAX_DEBUG_CONTENT_LENGTH] + "..." if len(content) > MAX_DEBUG_CONTENT_LENGTH else content
			)
			logger.debug("Parsing JSON content: %s", debug_content)

			# Handle both direct JSON objects and strings containing JSON
			if not content.strip().startswith("{"):
				# Extract JSON if it's wrapped in other text
				import re

				json_match = re.search(r"({.*})", content, re.DOTALL)
				if json_match:
					content = json_match.group(1)

			message_data = json.loads(content)
			logger.debug("Parsed JSON: %s", message_data)

			# Basic Schema Validation
			if not isinstance(message_data, dict):
				_raise_validation_error("JSON response is not an object")

			if not message_data.get("type") or not message_data.get("description"):
				_raise_validation_error("Missing required fields in JSON response")

			# Extract components with validation/defaults
			commit_type = str(message_data["type"]).lower().strip()

			# Check for valid commit type (from the config)
			valid_types = self._config_loader.get_commit_convention().get("types", [])
			if valid_types and commit_type not in valid_types:
				logger.warning("Invalid commit type: %s. Valid types: %s", commit_type, valid_types)
				# Try to find a valid type as fallback
				if "feat" in valid_types:
					commit_type = "feat"
				elif "fix" in valid_types:
					commit_type = "fix"
				elif len(valid_types) > 0:
					commit_type = valid_types[0]
				logger.debug("Using fallback commit type: %s", commit_type)

			scope = message_data.get("scope")
			if scope is not None:
				scope = str(scope).lower().strip()

			description = str(message_data["description"]).lower().strip()

			# Ensure description doesn't start with another type prefix
			for valid_type in valid_types:
				if description.startswith(f"{valid_type}:"):
					# Remove the duplicate type prefix from description
					description = description.split(":", 1)[1].strip()
					logger.debug("Removed duplicate type prefix from description: %s", description)
					break

			body = message_data.get("body")
			if body is not None:
				body = str(body).strip()
			is_breaking = bool(message_data.get("breaking", False))

			# Format the header
			header = f"{commit_type}"
			if scope:
				header += f"({scope})"
			if is_breaking:
				header += "!"
			header += f": {description}"

			# Ensure compliance with commit format regex
			# The regex requires a space after the colon, and the format should be <type>(<scope>)!: <description>
			if ": " not in header:
				parts = header.split(":")
				if len(parts) == EXPECTED_PARTS_COUNT:
					header = f"{parts[0]}: {parts[1].strip()}"

			# Validation check against regex pattern
			import re

			from codemap.git.commit_linter.constants import COMMIT_REGEX

			# If header doesn't match the expected format, log and try to fix it
			if not COMMIT_REGEX.match(header):
				logger.warning("Generated header doesn't match commit format: %s", header)
				# As a fallback, recreate with a simpler format
				simple_header = f"{commit_type}"
				if scope:
					simple_header += f"({scope})"
				if is_breaking:
					simple_header += "!"
				simple_header += f": {description}"
				header = simple_header
				logger.debug("Fixed header to: %s", header)

			# Build the complete message
			message_parts = [header]

			# Add body if provided
			if body:
				message_parts.append("")  # Empty line between header and body
				message_parts.append(body)

			# Carefully filter only breaking change footers
			footers = message_data.get("footers", [])
			breaking_change_footers = []

			if isinstance(footers, list):
				breaking_change_footers = [
					footer
					for footer in footers
					if isinstance(footer, dict)
					and footer.get("token", "").upper() in ("BREAKING CHANGE", "BREAKING-CHANGE")
				]

			if breaking_change_footers:
				if not body:
					message_parts.append("")  # Empty line before footers if no body
				else:
					message_parts.append("")  # Empty line between body and footers

				for footer in breaking_change_footers:
					token = footer.get("token", "")
					value = footer.get("value", "")
					message_parts.append(f"{token}: {value}")

			message = "\n".join(message_parts)
			logger.debug("Formatted commit message: %s", message)
			return message

		except (json.JSONDecodeError, ValueError, TypeError, AttributeError) as e:
			# If parsing or validation fails, return the content as-is, but cleaned
			logger.warning("Error formatting JSON to commit message: %s. Using raw content.", str(e))
			return content.strip()

	def fallback_generation(self, chunk: DiffChunk) -> str:
		"""
		Generate a fallback commit message without LLM.

		This is used when LLM-based generation fails or is disabled.

		Args:
		    chunk: Diff chunk object to generate message for

		Returns:
		    Generated commit message

		"""
		commit_type = "chore"

		# Get files directly from the chunk object
		files = chunk.files

		# Filter only strings (defensive, though DiffChunk.files should be list[str])
		string_files = [f for f in files if isinstance(f, str)]

		for file in string_files:
			if file.startswith("tests/"):
				commit_type = "test"
				break
			if file.startswith("docs/") or file.endswith(".md"):
				commit_type = "docs"
				break

		# Get content directly from the chunk object
		content = chunk.content

		if isinstance(content, str) and ("fix" in content.lower() or "bug" in content.lower()):
			commit_type = "fix"  # Be slightly smarter about 'fix' type

		# Use chunk description if available and seems specific (not just placeholder)
		chunk_desc = chunk.description
		placeholder_descs = ["update files", "changes in", "hunk in", "new file:"]
		# Ensure chunk_desc is not None before calling lower()
		use_chunk_desc = chunk_desc and not any(p in chunk_desc.lower() for p in placeholder_descs)

		if use_chunk_desc and chunk_desc:  # Add explicit check for chunk_desc
			description = chunk_desc
			# Attempt to extract a type from the chunk description if possible
			# Ensure chunk_desc is not None before calling lower() and split()
			if chunk_desc.lower().startswith(
				("feat", "fix", "refactor", "docs", "test", "chore", "style", "perf", "ci", "build")
			):
				parts = chunk_desc.split(":", 1)
				if len(parts) > 1:
					commit_type = parts[0].split("(")[0].strip().lower()  # Extract type before scope
					description = parts[1].strip()
		else:
			# Generate description based on file count/path if no specific chunk desc
			description = "update files"  # Default
			if string_files:
				if len(string_files) == 1:
					description = f"update {string_files[0]}"
				else:
					try:
						common_dir = os.path.commonpath(string_files)
						# Make common_dir relative to repo root if possible
						try:
							common_dir_rel = os.path.relpath(common_dir, self.repo_root)
							if common_dir_rel and common_dir_rel != ".":
								description = f"update files in {common_dir_rel}"
							else:
								description = f"update {len(string_files)} files"
						except ValueError:  # Happens if paths are on different drives (unlikely in repo)
							description = f"update {len(string_files)} files"

					except (ValueError, TypeError):  # commonpath fails on empty list or mixed types
						description = f"update {len(string_files)} files"

		message = f"{commit_type}: {description}"
		logger.debug("Generated fallback message: %s", message)
		return message

	def generate_message(self, chunk: DiffChunk) -> tuple[str, bool]:
		"""
		Generate a commit message for a diff chunk.

		Args:
		    chunk: Diff chunk to generate message for

		Returns:
		    Generated message and success flag

		"""
		# Prepare prompt with chunk data
		try:
			prompt = self._prepare_prompt(chunk)
			logger.debug("Prompt prepared successfully")

			# Generate message using configured LLM provider
			message = self._call_llm_api(prompt)
			logger.debug("LLM generated message: %s", message)

			# Return generated message with success flag
			return message, True
		except (ValueError, TypeError, KeyError, LLMError):
			logger.exception("Error during LLM generation")
			# Fall back to heuristic generation
			return self.fallback_generation(chunk), False

	def _call_llm_api(self, prompt: str) -> str:
		"""
		Call the LLM API with the given prompt.

		Args:
		    prompt: Prompt to send to the LLM

		Returns:
		    Raw response content from the LLM

		Raises:
		    LLMError: If the API call fails

		"""
		# Directly use the generate_text method from the LLMClient
		return self.client.generate_text(prompt=prompt, json_schema=COMMIT_MESSAGE_SCHEMA)

	def generate_message_with_linting(
		self, chunk: DiffChunk, retry_count: int = 1, max_retries: int = 3
	) -> tuple[str, bool, bool, list[str]]:
		"""
		Generate a commit message with linting verification.

		Args:
		        chunk: The DiffChunk to generate a message for
		        retry_count: Current retry count (default: 1)
		        max_retries: Maximum number of retries for linting (default: 3)

		Returns:
		        Tuple of (message, used_llm, passed_linting, lint_messages)

		"""
		# First, generate the initial message
		initial_lint_messages: list[str] = []  # Store initial messages
		try:
			message, used_llm = self.generate_message(chunk)
			logger.debug("Generated initial message: %s", message)

			# Clean the message before linting
			message = clean_message_for_linting(message)

			# Check if the message passes linting
			is_valid, error_message = lint_commit_message(
				message, repo_root=self.repo_root, config_loader=self._config_loader
			)
			initial_lint_messages = [error_message] if error_message is not None else []
			logger.debug("Lint result: valid=%s, messages=%s", is_valid, initial_lint_messages)

			if is_valid or retry_count >= max_retries:
				# Return empty list if valid, or initial messages if max retries reached
				return message, used_llm, is_valid, [] if is_valid else initial_lint_messages

			# Prepare the diff content
			diff_content = chunk.content
			if not diff_content:
				# Check if we have binary files in the chunk
				binary_files = []
				for file_path in chunk.files:
					# First check file extension
					extension = ""
					file_info = self.extract_file_info(chunk)
					if file_path in file_info:
						extension = file_info[file_path].get("extension", "").lower()
						binary_extensions = {
							"png",
							"jpg",
							"jpeg",
							"gif",
							"bmp",
							"ico",
							"webp",
							"mp3",
							"wav",
							"mp4",
							"avi",
							"mov",
							"pdf",
							"zip",
							"tar",
							"gz",
							"exe",
							"dll",
							"so",
						}
						if extension in binary_extensions:
							binary_files.append(file_path)

					# Also try to detect binary files directly
					abs_path = self.repo_root / file_path
					try:
						if abs_path.exists():
							from codemap.utils.file_utils import is_binary_file

							if is_binary_file(abs_path) and file_path not in binary_files:
								binary_files.append(file_path)
					except (OSError, PermissionError) as e:
						# If any error occurs during binary check, log it and continue
						logger.debug("Error checking if %s is binary: %s", file_path, str(e))

				if binary_files:
					# Create a more descriptive message for binary files
					diff_content = "Binary files detected in this chunk:\n"
					for binary_file in binary_files:
						diff_content += f"- {binary_file}\n"
				else:
					# Generic fallback for empty diff with no binary files detected
					diff_content = "Empty diff (likely modified binary files)"

			logger.info("Regenerating message with linting feedback (attempt %d/%d)", retry_count, max_retries)

			try:
				# Prepare the enhanced prompt for regeneration
				lint_template = get_lint_prompt_template()
				enhanced_prompt = prepare_lint_prompt(
					template=lint_template,
					file_info=self.extract_file_info(chunk),  # Use self
					convention=self.get_commit_convention(),  # Use self
					lint_messages=initial_lint_messages,  # Use initial messages for feedback
					original_message=message,  # Pass the original message that failed linting
				)

				# Generate message with the enhanced prompt
				regenerated_message = self._call_llm_api(enhanced_prompt)
				logger.debug("Regenerated message (RAW LLM output): %s", regenerated_message)

				# Format from JSON to commit message format
				regenerated_message = self.format_json_to_commit_message(regenerated_message)
				logger.debug("Formatted message: %s", regenerated_message)

				# Clean and recheck linting
				cleaned_message = clean_message_for_linting(regenerated_message)
				logger.debug("Cleaned message for linting: %s", cleaned_message)

				# Check if the message passes linting
				final_is_valid, error_message = lint_commit_message(
					cleaned_message, repo_root=self.repo_root, config_loader=self._config_loader
				)
				final_lint_messages = [error_message] if error_message is not None else []
				logger.debug("Regenerated lint result: valid=%s, messages=%s", final_is_valid, final_lint_messages)

				# Return final result and messages (empty if valid)
				return cleaned_message, True, final_is_valid, [] if final_is_valid else final_lint_messages
			except (ValueError, TypeError, KeyError, LLMError, json.JSONDecodeError):
				# If regeneration fails, log it and return the original message and its lint errors
				logger.exception("Error during message regeneration")
				return message, used_llm, False, initial_lint_messages  # Return original message and errors
		except (ValueError, TypeError, KeyError, LLMError, json.JSONDecodeError):
			# If generation fails completely, use a fallback (fallback doesn't lint, so return True, empty messages)
			logger.exception("Error during message generation")
			message = self.fallback_generation(chunk)
			return message, False, True, []  # Fallback assumes valid, no lint messages

	def get_config_loader(self) -> ConfigLoader:
		"""
		Get the ConfigLoader instance used by this generator.

		Returns:
		    ConfigLoader instance

		"""
		return self._config_loader

__init__

__init__(
	repo_root: Path,
	llm_client: LLMClient,
	prompt_template: str,
	config_loader: ConfigLoader,
) -> None

Initialize the commit message generator.

Parameters:

Name	Type	Description	Default
repo_root	Path	Root directory of the Git repository	required
llm_client	LLMClient	LLMClient instance to use	required
prompt_template	str	Custom prompt template to use	required
config_loader	ConfigLoader	ConfigLoader instance to use for configuration	required

Source code in src/codemap/git/commit_generator/generator.py

def __init__(
	self,
	repo_root: Path,
	llm_client: LLMClient,
	prompt_template: str,
	config_loader: ConfigLoader,
) -> None:
	"""
	Initialize the commit message generator.

	Args:
	    repo_root: Root directory of the Git repository
	    llm_client: LLMClient instance to use
	    prompt_template: Custom prompt template to use
	    config_loader: ConfigLoader instance to use for configuration

	"""
	self.repo_root = repo_root
	self.prompt_template = prompt_template
	self._config_loader = config_loader
	self.client = llm_client

	# Add commit template to client
	self.client.set_template("commit", self.prompt_template)

	# Get max token limit from config
	llm_config = self._config_loader.get("llm", {})
	self.max_tokens = llm_config.get("max_context_tokens", 4000)

	# Flag to control whether to use the LOD-based context processing
	self.use_lod_context = llm_config.get("use_lod_context", True)

repo_root instance-attribute

repo_root = repo_root

prompt_template instance-attribute

prompt_template = prompt_template

client instance-attribute

client = llm_client

max_tokens instance-attribute

max_tokens = get('max_context_tokens', 4000)

use_lod_context instance-attribute

use_lod_context = get('use_lod_context', True)

extract_file_info

extract_file_info(chunk: DiffChunk) -> dict[str, Any]

Extract file information from the diff chunk.

Parameters:

Name	Type	Description	Default
chunk	DiffChunk	Diff chunk object to extract information from	required

Returns:

Type	Description
dict[str, Any]	Dictionary with information about files

Source code in src/codemap/git/commit_generator/generator.py

def extract_file_info(self, chunk: DiffChunk) -> dict[str, Any]:
	"""
	Extract file information from the diff chunk.

	Args:
	    chunk: Diff chunk object to extract information from

	Returns:
	    Dictionary with information about files

	"""
	file_info = {}
	files = chunk.files
	for file in files:
		if not isinstance(file, str):
			continue  # Skip non-string file entries
		file_path = self.repo_root / file
		if not file_path.exists():
			continue
		try:
			extension = file_path.suffix.lstrip(".")
			file_info[file] = {
				"extension": extension,
				"directory": str(file_path.parent.relative_to(self.repo_root)),
			}
			path_parts = file_path.parts
			if len(path_parts) > 1:
				if "src" in path_parts:
					idx = path_parts.index("src")
					if idx + 1 < len(path_parts):
						file_info[file]["module"] = path_parts[idx + 1]
				elif "tests" in path_parts:
					file_info[file]["module"] = "tests"
		except (ValueError, IndexError, TypeError):
			continue
	return file_info

get_commit_convention

get_commit_convention() -> dict[str, Any]

Get commit convention settings from config.

Source code in src/codemap/git/commit_generator/generator.py

def get_commit_convention(self) -> dict[str, Any]:
	"""Get commit convention settings from config."""
	# Use the centralized ConfigLoader to get the convention
	return self._config_loader.get_commit_convention()

format_json_to_commit_message

format_json_to_commit_message(content: str) -> str

Format a JSON string as a conventional commit message.

Parameters:

Name	Type	Description	Default
content	str	JSON content string from LLM response	required

Returns:

Type	Description
str	Formatted commit message string

Source code in src/codemap/git/commit_generator/generator.py

def format_json_to_commit_message(self, content: str) -> str:
	"""
	Format a JSON string as a conventional commit message.

	Args:
	    content: JSON content string from LLM response

	Returns:
	    Formatted commit message string

	"""

	def _raise_validation_error(message: str) -> None:
		"""Helper to raise ValueError with consistent message."""
		logger.warning("LLM response validation failed: %s", message)
		msg = message
		raise ValueError(msg)

	try:
		# Try to parse the content as JSON
		debug_content = (
			content[:MAX_DEBUG_CONTENT_LENGTH] + "..." if len(content) > MAX_DEBUG_CONTENT_LENGTH else content
		)
		logger.debug("Parsing JSON content: %s", debug_content)

		# Handle both direct JSON objects and strings containing JSON
		if not content.strip().startswith("{"):
			# Extract JSON if it's wrapped in other text
			import re

			json_match = re.search(r"({.*})", content, re.DOTALL)
			if json_match:
				content = json_match.group(1)

		message_data = json.loads(content)
		logger.debug("Parsed JSON: %s", message_data)

		# Basic Schema Validation
		if not isinstance(message_data, dict):
			_raise_validation_error("JSON response is not an object")

		if not message_data.get("type") or not message_data.get("description"):
			_raise_validation_error("Missing required fields in JSON response")

		# Extract components with validation/defaults
		commit_type = str(message_data["type"]).lower().strip()

		# Check for valid commit type (from the config)
		valid_types = self._config_loader.get_commit_convention().get("types", [])
		if valid_types and commit_type not in valid_types:
			logger.warning("Invalid commit type: %s. Valid types: %s", commit_type, valid_types)
			# Try to find a valid type as fallback
			if "feat" in valid_types:
				commit_type = "feat"
			elif "fix" in valid_types:
				commit_type = "fix"
			elif len(valid_types) > 0:
				commit_type = valid_types[0]
			logger.debug("Using fallback commit type: %s", commit_type)

		scope = message_data.get("scope")
		if scope is not None:
			scope = str(scope).lower().strip()

		description = str(message_data["description"]).lower().strip()

		# Ensure description doesn't start with another type prefix
		for valid_type in valid_types:
			if description.startswith(f"{valid_type}:"):
				# Remove the duplicate type prefix from description
				description = description.split(":", 1)[1].strip()
				logger.debug("Removed duplicate type prefix from description: %s", description)
				break

		body = message_data.get("body")
		if body is not None:
			body = str(body).strip()
		is_breaking = bool(message_data.get("breaking", False))

		# Format the header
		header = f"{commit_type}"
		if scope:
			header += f"({scope})"
		if is_breaking:
			header += "!"
		header += f": {description}"

		# Ensure compliance with commit format regex
		# The regex requires a space after the colon, and the format should be <type>(<scope>)!: <description>
		if ": " not in header:
			parts = header.split(":")
			if len(parts) == EXPECTED_PARTS_COUNT:
				header = f"{parts[0]}: {parts[1].strip()}"

		# Validation check against regex pattern
		import re

		from codemap.git.commit_linter.constants import COMMIT_REGEX

		# If header doesn't match the expected format, log and try to fix it
		if not COMMIT_REGEX.match(header):
			logger.warning("Generated header doesn't match commit format: %s", header)
			# As a fallback, recreate with a simpler format
			simple_header = f"{commit_type}"
			if scope:
				simple_header += f"({scope})"
			if is_breaking:
				simple_header += "!"
			simple_header += f": {description}"
			header = simple_header
			logger.debug("Fixed header to: %s", header)

		# Build the complete message
		message_parts = [header]

		# Add body if provided
		if body:
			message_parts.append("")  # Empty line between header and body
			message_parts.append(body)

		# Carefully filter only breaking change footers
		footers = message_data.get("footers", [])
		breaking_change_footers = []

		if isinstance(footers, list):
			breaking_change_footers = [
				footer
				for footer in footers
				if isinstance(footer, dict)
				and footer.get("token", "").upper() in ("BREAKING CHANGE", "BREAKING-CHANGE")
			]

		if breaking_change_footers:
			if not body:
				message_parts.append("")  # Empty line before footers if no body
			else:
				message_parts.append("")  # Empty line between body and footers

			for footer in breaking_change_footers:
				token = footer.get("token", "")
				value = footer.get("value", "")
				message_parts.append(f"{token}: {value}")

		message = "\n".join(message_parts)
		logger.debug("Formatted commit message: %s", message)
		return message

	except (json.JSONDecodeError, ValueError, TypeError, AttributeError) as e:
		# If parsing or validation fails, return the content as-is, but cleaned
		logger.warning("Error formatting JSON to commit message: %s. Using raw content.", str(e))
		return content.strip()

fallback_generation

fallback_generation(chunk: DiffChunk) -> str

Generate a fallback commit message without LLM.

This is used when LLM-based generation fails or is disabled.

Parameters:

Name	Type	Description	Default
chunk	DiffChunk	Diff chunk object to generate message for	required

Returns:

Type	Description
str	Generated commit message

Source code in src/codemap/git/commit_generator/generator.py

def fallback_generation(self, chunk: DiffChunk) -> str:
	"""
	Generate a fallback commit message without LLM.

	This is used when LLM-based generation fails or is disabled.

	Args:
	    chunk: Diff chunk object to generate message for

	Returns:
	    Generated commit message

	"""
	commit_type = "chore"

	# Get files directly from the chunk object
	files = chunk.files

	# Filter only strings (defensive, though DiffChunk.files should be list[str])
	string_files = [f for f in files if isinstance(f, str)]

	for file in string_files:
		if file.startswith("tests/"):
			commit_type = "test"
			break
		if file.startswith("docs/") or file.endswith(".md"):
			commit_type = "docs"
			break

	# Get content directly from the chunk object
	content = chunk.content

	if isinstance(content, str) and ("fix" in content.lower() or "bug" in content.lower()):
		commit_type = "fix"  # Be slightly smarter about 'fix' type

	# Use chunk description if available and seems specific (not just placeholder)
	chunk_desc = chunk.description
	placeholder_descs = ["update files", "changes in", "hunk in", "new file:"]
	# Ensure chunk_desc is not None before calling lower()
	use_chunk_desc = chunk_desc and not any(p in chunk_desc.lower() for p in placeholder_descs)

	if use_chunk_desc and chunk_desc:  # Add explicit check for chunk_desc
		description = chunk_desc
		# Attempt to extract a type from the chunk description if possible
		# Ensure chunk_desc is not None before calling lower() and split()
		if chunk_desc.lower().startswith(
			("feat", "fix", "refactor", "docs", "test", "chore", "style", "perf", "ci", "build")
		):
			parts = chunk_desc.split(":", 1)
			if len(parts) > 1:
				commit_type = parts[0].split("(")[0].strip().lower()  # Extract type before scope
				description = parts[1].strip()
	else:
		# Generate description based on file count/path if no specific chunk desc
		description = "update files"  # Default
		if string_files:
			if len(string_files) == 1:
				description = f"update {string_files[0]}"
			else:
				try:
					common_dir = os.path.commonpath(string_files)
					# Make common_dir relative to repo root if possible
					try:
						common_dir_rel = os.path.relpath(common_dir, self.repo_root)
						if common_dir_rel and common_dir_rel != ".":
							description = f"update files in {common_dir_rel}"
						else:
							description = f"update {len(string_files)} files"
					except ValueError:  # Happens if paths are on different drives (unlikely in repo)
						description = f"update {len(string_files)} files"

				except (ValueError, TypeError):  # commonpath fails on empty list or mixed types
					description = f"update {len(string_files)} files"

	message = f"{commit_type}: {description}"
	logger.debug("Generated fallback message: %s", message)
	return message

generate_message

generate_message(chunk: DiffChunk) -> tuple[str, bool]

Generate a commit message for a diff chunk.

Parameters:

Name	Type	Description	Default
chunk	DiffChunk	Diff chunk to generate message for	required

Returns:

Type	Description
tuple[str, bool]	Generated message and success flag

Source code in src/codemap/git/commit_generator/generator.py

def generate_message(self, chunk: DiffChunk) -> tuple[str, bool]:
	"""
	Generate a commit message for a diff chunk.

	Args:
	    chunk: Diff chunk to generate message for

	Returns:
	    Generated message and success flag

	"""
	# Prepare prompt with chunk data
	try:
		prompt = self._prepare_prompt(chunk)
		logger.debug("Prompt prepared successfully")

		# Generate message using configured LLM provider
		message = self._call_llm_api(prompt)
		logger.debug("LLM generated message: %s", message)

		# Return generated message with success flag
		return message, True
	except (ValueError, TypeError, KeyError, LLMError):
		logger.exception("Error during LLM generation")
		# Fall back to heuristic generation
		return self.fallback_generation(chunk), False

generate_message_with_linting

generate_message_with_linting(
	chunk: DiffChunk,
	retry_count: int = 1,
	max_retries: int = 3,
) -> tuple[str, bool, bool, list[str]]

Generate a commit message with linting verification.

Parameters:

Name	Type	Description	Default
chunk	DiffChunk	The DiffChunk to generate a message for	required
retry_count	int	Current retry count (default: 1)	1
max_retries	int	Maximum number of retries for linting (default: 3)	3

Returns:

Type	Description
tuple[str, bool, bool, list[str]]	Tuple of (message, used_llm, passed_linting, lint_messages)

Source code in src/codemap/git/commit_generator/generator.py

def generate_message_with_linting(
	self, chunk: DiffChunk, retry_count: int = 1, max_retries: int = 3
) -> tuple[str, bool, bool, list[str]]:
	"""
	Generate a commit message with linting verification.

	Args:
	        chunk: The DiffChunk to generate a message for
	        retry_count: Current retry count (default: 1)
	        max_retries: Maximum number of retries for linting (default: 3)

	Returns:
	        Tuple of (message, used_llm, passed_linting, lint_messages)

	"""
	# First, generate the initial message
	initial_lint_messages: list[str] = []  # Store initial messages
	try:
		message, used_llm = self.generate_message(chunk)
		logger.debug("Generated initial message: %s", message)

		# Clean the message before linting
		message = clean_message_for_linting(message)

		# Check if the message passes linting
		is_valid, error_message = lint_commit_message(
			message, repo_root=self.repo_root, config_loader=self._config_loader
		)
		initial_lint_messages = [error_message] if error_message is not None else []
		logger.debug("Lint result: valid=%s, messages=%s", is_valid, initial_lint_messages)

		if is_valid or retry_count >= max_retries:
			# Return empty list if valid, or initial messages if max retries reached
			return message, used_llm, is_valid, [] if is_valid else initial_lint_messages

		# Prepare the diff content
		diff_content = chunk.content
		if not diff_content:
			# Check if we have binary files in the chunk
			binary_files = []
			for file_path in chunk.files:
				# First check file extension
				extension = ""
				file_info = self.extract_file_info(chunk)
				if file_path in file_info:
					extension = file_info[file_path].get("extension", "").lower()
					binary_extensions = {
						"png",
						"jpg",
						"jpeg",
						"gif",
						"bmp",
						"ico",
						"webp",
						"mp3",
						"wav",
						"mp4",
						"avi",
						"mov",
						"pdf",
						"zip",
						"tar",
						"gz",
						"exe",
						"dll",
						"so",
					}
					if extension in binary_extensions:
						binary_files.append(file_path)

				# Also try to detect binary files directly
				abs_path = self.repo_root / file_path
				try:
					if abs_path.exists():
						from codemap.utils.file_utils import is_binary_file

						if is_binary_file(abs_path) and file_path not in binary_files:
							binary_files.append(file_path)
				except (OSError, PermissionError) as e:
					# If any error occurs during binary check, log it and continue
					logger.debug("Error checking if %s is binary: %s", file_path, str(e))

			if binary_files:
				# Create a more descriptive message for binary files
				diff_content = "Binary files detected in this chunk:\n"
				for binary_file in binary_files:
					diff_content += f"- {binary_file}\n"
			else:
				# Generic fallback for empty diff with no binary files detected
				diff_content = "Empty diff (likely modified binary files)"

		logger.info("Regenerating message with linting feedback (attempt %d/%d)", retry_count, max_retries)

		try:
			# Prepare the enhanced prompt for regeneration
			lint_template = get_lint_prompt_template()
			enhanced_prompt = prepare_lint_prompt(
				template=lint_template,
				file_info=self.extract_file_info(chunk),  # Use self
				convention=self.get_commit_convention(),  # Use self
				lint_messages=initial_lint_messages,  # Use initial messages for feedback
				original_message=message,  # Pass the original message that failed linting
			)

			# Generate message with the enhanced prompt
			regenerated_message = self._call_llm_api(enhanced_prompt)
			logger.debug("Regenerated message (RAW LLM output): %s", regenerated_message)

			# Format from JSON to commit message format
			regenerated_message = self.format_json_to_commit_message(regenerated_message)
			logger.debug("Formatted message: %s", regenerated_message)

			# Clean and recheck linting
			cleaned_message = clean_message_for_linting(regenerated_message)
			logger.debug("Cleaned message for linting: %s", cleaned_message)

			# Check if the message passes linting
			final_is_valid, error_message = lint_commit_message(
				cleaned_message, repo_root=self.repo_root, config_loader=self._config_loader
			)
			final_lint_messages = [error_message] if error_message is not None else []
			logger.debug("Regenerated lint result: valid=%s, messages=%s", final_is_valid, final_lint_messages)

			# Return final result and messages (empty if valid)
			return cleaned_message, True, final_is_valid, [] if final_is_valid else final_lint_messages
		except (ValueError, TypeError, KeyError, LLMError, json.JSONDecodeError):
			# If regeneration fails, log it and return the original message and its lint errors
			logger.exception("Error during message regeneration")
			return message, used_llm, False, initial_lint_messages  # Return original message and errors
	except (ValueError, TypeError, KeyError, LLMError, json.JSONDecodeError):
		# If generation fails completely, use a fallback (fallback doesn't lint, so return True, empty messages)
		logger.exception("Error during message generation")
		message = self.fallback_generation(chunk)
		return message, False, True, []  # Fallback assumes valid, no lint messages

get_config_loader

get_config_loader() -> ConfigLoader

Get the ConfigLoader instance used by this generator.

Returns:

Type	Description
ConfigLoader	ConfigLoader instance

Source code in src/codemap/git/commit_generator/generator.py

def get_config_loader(self) -> ConfigLoader:
	"""
	Get the ConfigLoader instance used by this generator.

	Returns:
	    ConfigLoader instance

	"""
	return self._config_loader

DEFAULT_PROMPT_TEMPLATE module-attribute

DEFAULT_PROMPT_TEMPLATE = '\nYou are an AI assistant generating Conventional Commit 1.0.0 messages from Git diffs.\n\n**Format:**\n```\n<type>[optional scope]: <description>\n\n[optional body]\n\n[optional footer(s)]\n```\n\n**Instructions & Rules:**\n\n1.  **Type:** REQUIRED. Must be lowercase and one of: {convention[types]}.\n    *   `feat`: New feature (MINOR SemVer).\n    *   `fix`: Bug fix (PATCH SemVer).\n    *   Other types (`build`, `chore`, `ci`, `docs`, `style`, `refactor`, `perf`, `test`, etc.) are allowed.\n2.  **Scope:** OPTIONAL. Lowercase noun(s) in parentheses describing the code section (e.g., `(parser)`).\n    *   Keep short (1-2 words).\n3.  **Description:** REQUIRED. Concise, imperative, present tense summary of *what* changed and *why* based on the diff.\n    *   Must follow the colon and space.\n    *   Must be >= 10 characters.\n    *   Must NOT end with a period.\n    *   The entire header line (`<type>[scope]: <description>`) must be <= {convention[max_length]} characters.\n4.  **Body:** OPTIONAL. Explain *why* and *how*. Start one blank line after the description.\n\t*\tUse the body only if extra context is needed to understand the changes.\n\t*\tDo not use the body to add unrelated information.\n\t*\tDo not use the body to explain *what* was changed.\n\t*\tTry to keep the body concise and to the point.\n5.  **Footer(s):** OPTIONAL. Format `Token: value` or `Token # value`.\n    *   Start one blank line after the body.\n    *   Use `-` for spaces in tokens (e.g., `Reviewed-by`).\n6.  **BREAKING CHANGE:** Indicate with `!` before the colon in the header (e.g., `feat(api)!: ...`)\n    *   OR with a `BREAKING CHANGE: <description>` footer (MUST be uppercase).\n    *   Correlates with MAJOR SemVer.\n    *   If `!` is used, the description explains the break.\n7.  **Special Case - Binary Files:**\n    *   For binary file changes, use `chore` type with a scope indicating the file type (e.g., `(assets)`, `(images)`, `(builds)`)\n    *   Be specific about what changed (e.g., "update image assets", "add new icon files", "replace binary database")\n    *   If the diff content is empty or shows binary file changes, focus on the filenames to determine the purpose\n\n**Input:**\n\n*   File notes: {files}\n*   Git diff: {diff}\n\n**Output Requirements:**\n\n*   Respond with ONLY the raw commit message string.\n*   NO extra text, explanations, or markdown formatting (like ```).\n*   STRICTLY OMIT footers: `Related Issue #`, `Closes #`, `REVIEWED-BY`, `TRACKING #`, `APPROVED`.\n\n**(IMPORTANT) Following JSON Schema must be followed for Output:**\n{schema}\n\n---\nPlease return the commit message in a valid json format. Analyze the following diff and generate the commit message:\n\n{diff}\n'

prepare_prompt

prepare_prompt(
	template: str,
	diff_content: str,
	file_info: dict[str, Any],
	convention: dict[str, Any],
	extra_context: dict[str, Any] | None = None,
) -> str

Prepare the prompt for the LLM.

Parameters:

Name	Type	Description	Default
template	str	Prompt template to use	required
diff_content	str	Diff content to include	required
file_info	dict[str, Any]	Information about files in the diff	required
convention	dict[str, Any]	Commit convention settings	required
extra_context	dict[str, Any] | None	Optional additional context values for the template	None

Returns:

Type	Description
str	Formatted prompt

Source code in src/codemap/git/commit_generator/prompts.py

def prepare_prompt(
	template: str,
	diff_content: str,
	file_info: dict[str, Any],
	convention: dict[str, Any],
	extra_context: dict[str, Any] | None = None,
) -> str:
	"""
	Prepare the prompt for the LLM.

	Args:
	    template: Prompt template to use
	    diff_content: Diff content to include
	    file_info: Information about files in the diff
	    convention: Commit convention settings
	    extra_context: Optional additional context values for the template

	Returns:
	    Formatted prompt

	"""
	context = {
		"diff": diff_content,
		"files": file_info,
		"convention": convention,
		"schema": COMMIT_MESSAGE_SCHEMA,
	}

	# Add any extra context values
	if extra_context:
		context.update(extra_context)

	try:
		return template.format(**context)
	except KeyError as e:
		msg = f"Prompt template formatting error. Missing key: {e}"
		raise ValueError(msg) from e

COMMIT_MESSAGE_SCHEMA module-attribute

COMMIT_MESSAGE_SCHEMA = {
	"type": "object",
	"properties": {
		"type": {
			"type": "string",
			"description": "The type of change (e.g., feat, fix, docs, style, refactor, perf, test, chore)",
		},
		"scope": {
			"type": ["string", "null"],
			"description": "The scope of the change (e.g., component affected)",
		},
		"description": {
			"type": "string",
			"description": "A short, imperative-tense description of the change",
		},
		"body": {
			"type": ["string", "null"],
			"description": "A longer description of the changes, explaining why and how",
		},
		"breaking": {
			"type": "boolean",
			"description": "Whether this is a breaking change",
			"default": False,
		},
		"footers": {
			"type": "array",
			"items": {
				"type": "object",
				"properties": {
					"token": {
						"type": "string",
						"description": "Footer token (e.g., 'BREAKING CHANGE', 'Fixes', 'Refs')",
					},
					"value": {
						"type": "string",
						"description": "Footer value",
					},
				},
				"required": ["token", "value"],
			},
			"default": [],
		},
	},
	"required": ["type", "description"],
}

CommitMessageSchema

Bases: TypedDict

TypedDict representing the structured commit message output.

Source code in src/codemap/git/commit_generator/schemas.py

class CommitMessageSchema(TypedDict):
	"""TypedDict representing the structured commit message output."""

	type: str
	scope: str | None
	description: str
	body: str | None
	breaking: bool
	footers: list[dict[str, str]]

type instance-attribute

type: str

scope instance-attribute

scope: str | None

description instance-attribute

description: str

body instance-attribute

body: str | None

breaking instance-attribute

breaking: bool

footers instance-attribute

footers: list[dict[str, str]]

clean_message_for_linting

clean_message_for_linting(message: str) -> str

Clean a commit message for linting.

Removes extra newlines, trims whitespace, etc.

Parameters:

Name	Type	Description	Default
message	str	The commit message to clean	required

Returns:

Type	Description
str	The cleaned commit message

Source code in src/codemap/git/commit_generator/utils.py

def clean_message_for_linting(message: str) -> str:
	"""
	Clean a commit message for linting.

	Removes extra newlines, trims whitespace, etc.

	Args:
	        message: The commit message to clean

	Returns:
	        The cleaned commit message

	"""
	# Replace multiple consecutive newlines with a single newline
	cleaned = re.sub(r"\n{3,}", "\n\n", message)
	# Trim leading and trailing whitespace
	return cleaned.strip()

lint_commit_message

lint_commit_message(
	message: str,
	repo_root: Path | None = None,
	config_loader: ConfigLoader | None = None,
) -> tuple[bool, str | None]

Lint a commit message.

Checks if it adheres to Conventional Commits format using internal CommitLinter.

Parameters:

Name	Type	Description	Default
message	str	The commit message to lint	required
repo_root	Path | None	Repository root path	None
config_loader	ConfigLoader | None	Configuration loader instance	None

Returns:

Type	Description
tuple[bool, str | None]	Tuple of (is_valid, error_message)

Source code in src/codemap/git/commit_generator/utils.py

def lint_commit_message(
	message: str, repo_root: Path | None = None, config_loader: ConfigLoader | None = None
) -> tuple[bool, str | None]:
	"""
	Lint a commit message.

	Checks if it adheres to Conventional Commits format using internal CommitLinter.

	Args:
	        message: The commit message to lint
	        repo_root: Repository root path
	        config_loader: Configuration loader instance

	Returns:
	        Tuple of (is_valid, error_message)

	"""
	# Get config loader if not provided
	if config_loader is None:
		config_loader = ConfigLoader(repo_root=repo_root)

	try:
		# Create a CommitLinter instance with the config_loader
		linter = CommitLinter(config_loader=config_loader)

		# Lint the commit message
		is_valid, lint_messages = linter.lint(message)

		# Get error message if not valid
		error_message = None
		if not is_valid and lint_messages:
			error_message = "\n".join(lint_messages)

		return is_valid, error_message

	except Exception as e:
		# Handle any errors during linting
		logger.exception("Error linting commit message")
		return False, f"Linting failed: {e!s}"

MessageGenerator module-attribute

MessageGenerator = CommitMessageGenerator

schemas

Schemas and data structures for commit message generation.

CommitMessageSchema

Bases: TypedDict

TypedDict representing the structured commit message output.

Source code in src/codemap/git/commit_generator/schemas.py

class CommitMessageSchema(TypedDict):
	"""TypedDict representing the structured commit message output."""

	type: str
	scope: str | None
	description: str
	body: str | None
	breaking: bool
	footers: list[dict[str, str]]

type instance-attribute

type: str

scope instance-attribute

scope: str | None

description instance-attribute

description: str

body instance-attribute

body: str | None

breaking instance-attribute

breaking: bool

footers instance-attribute

footers: list[dict[str, str]]

COMMIT_MESSAGE_SCHEMA module-attribute

COMMIT_MESSAGE_SCHEMA = {
	"type": "object",
	"properties": {
		"type": {
			"type": "string",
			"description": "The type of change (e.g., feat, fix, docs, style, refactor, perf, test, chore)",
		},
		"scope": {
			"type": ["string", "null"],
			"description": "The scope of the change (e.g., component affected)",
		},
		"description": {
			"type": "string",
			"description": "A short, imperative-tense description of the change",
		},
		"body": {
			"type": ["string", "null"],
			"description": "A longer description of the changes, explaining why and how",
		},
		"breaking": {
			"type": "boolean",
			"description": "Whether this is a breaking change",
			"default": False,
		},
		"footers": {
			"type": "array",
			"items": {
				"type": "object",
				"properties": {
					"token": {
						"type": "string",
						"description": "Footer token (e.g., 'BREAKING CHANGE', 'Fixes', 'Refs')",
					},
					"value": {
						"type": "string",
						"description": "Footer value",
					},
				},
				"required": ["token", "value"],
			},
			"default": [],
		},
	},
	"required": ["type", "description"],
}

prompts

Prompt templates for commit message generation.

DEFAULT_PROMPT_TEMPLATE module-attribute

DEFAULT_PROMPT_TEMPLATE = '\nYou are an AI assistant generating Conventional Commit 1.0.0 messages from Git diffs.\n\n**Format:**\n```\n<type>[optional scope]: <description>\n\n[optional body]\n\n[optional footer(s)]\n```\n\n**Instructions & Rules:**\n\n1.  **Type:** REQUIRED. Must be lowercase and one of: {convention[types]}.\n    *   `feat`: New feature (MINOR SemVer).\n    *   `fix`: Bug fix (PATCH SemVer).\n    *   Other types (`build`, `chore`, `ci`, `docs`, `style`, `refactor`, `perf`, `test`, etc.) are allowed.\n2.  **Scope:** OPTIONAL. Lowercase noun(s) in parentheses describing the code section (e.g., `(parser)`).\n    *   Keep short (1-2 words).\n3.  **Description:** REQUIRED. Concise, imperative, present tense summary of *what* changed and *why* based on the diff.\n    *   Must follow the colon and space.\n    *   Must be >= 10 characters.\n    *   Must NOT end with a period.\n    *   The entire header line (`<type>[scope]: <description>`) must be <= {convention[max_length]} characters.\n4.  **Body:** OPTIONAL. Explain *why* and *how*. Start one blank line after the description.\n\t*\tUse the body only if extra context is needed to understand the changes.\n\t*\tDo not use the body to add unrelated information.\n\t*\tDo not use the body to explain *what* was changed.\n\t*\tTry to keep the body concise and to the point.\n5.  **Footer(s):** OPTIONAL. Format `Token: value` or `Token # value`.\n    *   Start one blank line after the body.\n    *   Use `-` for spaces in tokens (e.g., `Reviewed-by`).\n6.  **BREAKING CHANGE:** Indicate with `!` before the colon in the header (e.g., `feat(api)!: ...`)\n    *   OR with a `BREAKING CHANGE: <description>` footer (MUST be uppercase).\n    *   Correlates with MAJOR SemVer.\n    *   If `!` is used, the description explains the break.\n7.  **Special Case - Binary Files:**\n    *   For binary file changes, use `chore` type with a scope indicating the file type (e.g., `(assets)`, `(images)`, `(builds)`)\n    *   Be specific about what changed (e.g., "update image assets", "add new icon files", "replace binary database")\n    *   If the diff content is empty or shows binary file changes, focus on the filenames to determine the purpose\n\n**Input:**\n\n*   File notes: {files}\n*   Git diff: {diff}\n\n**Output Requirements:**\n\n*   Respond with ONLY the raw commit message string.\n*   NO extra text, explanations, or markdown formatting (like ```).\n*   STRICTLY OMIT footers: `Related Issue #`, `Closes #`, `REVIEWED-BY`, `TRACKING #`, `APPROVED`.\n\n**(IMPORTANT) Following JSON Schema must be followed for Output:**\n{schema}\n\n---\nPlease return the commit message in a valid json format. Analyze the following diff and generate the commit message:\n\n{diff}\n'

get_lint_prompt_template

get_lint_prompt_template() -> str

Get the prompt template for lint feedback.

Returns:

Type	Description
str	The prompt template with lint feedback placeholders

Source code in src/codemap/git/commit_generator/prompts.py

def get_lint_prompt_template() -> str:
	"""
	Get the prompt template for lint feedback.

	Returns:
	    The prompt template with lint feedback placeholders

	"""
	return """
You are a helpful assistant that fixes conventional commit messages that have linting errors.

1. The conventional commit format is:
```
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
```
2. Types include: {convention[types]}
3. Scope must be short (1-2 words), concise, and represent the specific component affected
4. The description should be a concise, imperative present tense summary of the code changes,
   focusing on *what* was changed and *why*.
5. The optional body should focus on the *why* and *how* of the changes.

IMPORTANT: The provided commit message has the following issues:
{lint_feedback}

Original commit message:
{original_message}

Brief file context (without full diff):
{files_summary}

Please fix these issues and ensure the generated message adheres to the commit convention.

IMPORTANT:
- Strictly follow the format <type>[optional scope]: <description>
- Do not include any other text, explanation, or surrounding characters
- Do not include any `Related Issue #`, `Closes #`, `REVIEWED-BY`, `TRACKING #`, `APPROVED` footers.
- Respond with a valid JSON object following this schema:

{schema}

Return your answer as json.
"""

prepare_prompt

prepare_prompt(
	template: str,
	diff_content: str,
	file_info: dict[str, Any],
	convention: dict[str, Any],
	extra_context: dict[str, Any] | None = None,
) -> str

Prepare the prompt for the LLM.

Parameters:

Name	Type	Description	Default
template	str	Prompt template to use	required
diff_content	str	Diff content to include	required
file_info	dict[str, Any]	Information about files in the diff	required
convention	dict[str, Any]	Commit convention settings	required
extra_context	dict[str, Any] | None	Optional additional context values for the template	None

Returns:

Type	Description
str	Formatted prompt

Source code in src/codemap/git/commit_generator/prompts.py

def prepare_prompt(
	template: str,
	diff_content: str,
	file_info: dict[str, Any],
	convention: dict[str, Any],
	extra_context: dict[str, Any] | None = None,
) -> str:
	"""
	Prepare the prompt for the LLM.

	Args:
	    template: Prompt template to use
	    diff_content: Diff content to include
	    file_info: Information about files in the diff
	    convention: Commit convention settings
	    extra_context: Optional additional context values for the template

	Returns:
	    Formatted prompt

	"""
	context = {
		"diff": diff_content,
		"files": file_info,
		"convention": convention,
		"schema": COMMIT_MESSAGE_SCHEMA,
	}

	# Add any extra context values
	if extra_context:
		context.update(extra_context)

	try:
		return template.format(**context)
	except KeyError as e:
		msg = f"Prompt template formatting error. Missing key: {e}"
		raise ValueError(msg) from e

prepare_lint_prompt

prepare_lint_prompt(
	template: str,
	file_info: dict[str, Any],
	convention: dict[str, Any],
	lint_messages: list[str],
	original_message: str | None = None,
) -> str

Prepare a prompt with lint feedback for regeneration.

Parameters:

Name	Type	Description	Default
template	str	Prompt template to use	required
file_info	dict[str, Any]	Information about files in the diff	required
convention	dict[str, Any]	Commit convention settings	required
lint_messages	list[str]	List of linting error messages	required
original_message	str | None	The original failed commit message	None

Returns:

Type	Description
str	Enhanced prompt with linting feedback

Source code in src/codemap/git/commit_generator/prompts.py

def prepare_lint_prompt(
	template: str,
	file_info: dict[str, Any],
	convention: dict[str, Any],
	lint_messages: list[str],
	original_message: str | None = None,
) -> str:
	"""
	Prepare a prompt with lint feedback for regeneration.

	Args:
	    template: Prompt template to use
	    file_info: Information about files in the diff
	    convention: Commit convention settings
	    lint_messages: List of linting error messages
	    original_message: The original failed commit message

	Returns:
	    Enhanced prompt with linting feedback

	"""
	# Create specific feedback for linting issues
	lint_feedback = "\n".join([f"- {msg}" for msg in lint_messages])

	# Create a simplified file summary without full diff content
	files_summary = []
	for file_path, info in file_info.items():
		extension = info.get("extension", "")
		directory = info.get("directory", "")
		module = info.get("module", "")
		summary = f"- {file_path} ({extension} file in {directory})"
		if module:
			summary += f", part of {module} module"
		files_summary.append(summary)

	files_summary_text = "\n".join(files_summary) if files_summary else "No file information available"

	# If original_message wasn't provided, use a placeholder
	message_to_fix = original_message or "No original message provided"

	# Create an enhanced context with linting feedback
	context = {
		"convention": convention,
		"schema": COMMIT_MESSAGE_SCHEMA,
		"lint_feedback": lint_feedback,
		"original_message": message_to_fix,
		"files_summary": files_summary_text,
	}

	try:
		return template.format(**context)
	except KeyError as e:
		msg = f"Lint prompt template formatting error. Missing key: {e}"
		raise ValueError(msg) from e

utils

Utility functions for commit message generation.

logger module-attribute

logger = getLogger(__name__)

clean_message_for_linting

clean_message_for_linting(message: str) -> str

Clean a commit message for linting.

Removes extra newlines, trims whitespace, etc.

Parameters:

Name	Type	Description	Default
message	str	The commit message to clean	required

Returns:

Type	Description
str	The cleaned commit message

Source code in src/codemap/git/commit_generator/utils.py

def clean_message_for_linting(message: str) -> str:
	"""
	Clean a commit message for linting.

	Removes extra newlines, trims whitespace, etc.

	Args:
	        message: The commit message to clean

	Returns:
	        The cleaned commit message

	"""
	# Replace multiple consecutive newlines with a single newline
	cleaned = re.sub(r"\n{3,}", "\n\n", message)
	# Trim leading and trailing whitespace
	return cleaned.strip()

lint_commit_message

lint_commit_message(
	message: str,
	repo_root: Path | None = None,
	config_loader: ConfigLoader | None = None,
) -> tuple[bool, str | None]

Lint a commit message.

Checks if it adheres to Conventional Commits format using internal CommitLinter.

Parameters:

Name	Type	Description	Default
message	str	The commit message to lint	required
repo_root	Path | None	Repository root path	None
config_loader	ConfigLoader | None	Configuration loader instance	None

Returns:

Type	Description
tuple[bool, str | None]	Tuple of (is_valid, error_message)

Source code in src/codemap/git/commit_generator/utils.py

def lint_commit_message(
	message: str, repo_root: Path | None = None, config_loader: ConfigLoader | None = None
) -> tuple[bool, str | None]:
	"""
	Lint a commit message.

	Checks if it adheres to Conventional Commits format using internal CommitLinter.

	Args:
	        message: The commit message to lint
	        repo_root: Repository root path
	        config_loader: Configuration loader instance

	Returns:
	        Tuple of (is_valid, error_message)

	"""
	# Get config loader if not provided
	if config_loader is None:
		config_loader = ConfigLoader(repo_root=repo_root)

	try:
		# Create a CommitLinter instance with the config_loader
		linter = CommitLinter(config_loader=config_loader)

		# Lint the commit message
		is_valid, lint_messages = linter.lint(message)

		# Get error message if not valid
		error_message = None
		if not is_valid and lint_messages:
			error_message = "\n".join(lint_messages)

		return is_valid, error_message

	except Exception as e:
		# Handle any errors during linting
		logger.exception("Error linting commit message")
		return False, f"Linting failed: {e!s}"

save_working_directory_state

save_working_directory_state(
	files: list[str], output_file: str
) -> bool

Save the current state of specified files to a patch file.

Parameters:

Name	Type	Description	Default
files	list[str]	List of file paths	required
output_file	str	Path to output patch file	required

Returns:

Name	Type	Description
bool	bool	Whether the operation was successful

Source code in src/codemap/git/commit_generator/utils.py

def save_working_directory_state(files: list[str], output_file: str) -> bool:
	"""
	Save the current state of specified files to a patch file.

	Args:
	        files: List of file paths
	        output_file: Path to output patch file

	Returns:
	        bool: Whether the operation was successful

	"""
	output_path = Path(output_file)

	try:
		if not files:
			# Nothing to save
			with output_path.open("w") as f:
				f.write("")
			return True

		# Generate diff for the specified files
		diff_cmd = ["git", "diff", "--", *files]
		diff_content = run_git_command(diff_cmd)

		# Write to output file
		with output_path.open("w") as f:
			f.write(diff_content)

		return True

	except (OSError, GitError):
		logger.exception("Error saving working directory state")
		return False

restore_working_directory_state

restore_working_directory_state(patch_file: str) -> bool

Restore the working directory state from a patch file.

Parameters:

Name	Type	Description	Default
patch_file	str	Path to patch file	required

Returns:

Name	Type	Description
bool	bool	Whether the operation was successful

Source code in src/codemap/git/commit_generator/utils.py

def restore_working_directory_state(patch_file: str) -> bool:
	"""
	Restore the working directory state from a patch file.

	Args:
	        patch_file: Path to patch file

	Returns:
	        bool: Whether the operation was successful

	"""
	patch_path = Path(patch_file)

	try:
		# Check if the patch file exists and is not empty
		if not patch_path.exists() or patch_path.stat().st_size == 0:
			return True  # Nothing to restore

		# Apply the patch
		run_git_command(["git", "apply", patch_file])
		return True

	except GitError:
		logger.exception("Error restoring working directory state")
		return False

format_commit_json

format_commit_json(
	content: str, config_loader: ConfigLoader | None = None
) -> str

Format a JSON string as a conventional commit message.

Parameters:

Name	Type	Description	Default
content	str	JSON content string from LLM response	required
config_loader	ConfigLoader | None	Optional ConfigLoader for commit conventions	None

Returns:

Type	Description
str	Formatted commit message string

Source code in src/codemap/git/commit_generator/utils.py

def format_commit_json(content: str, config_loader: ConfigLoader | None = None) -> str:
	"""
	Format a JSON string as a conventional commit message.

	Args:
	        content: JSON content string from LLM response
	        config_loader: Optional ConfigLoader for commit conventions

	Returns:
	        Formatted commit message string

	"""

	def _raise_validation_error(message: str) -> None:
		"""Helper to raise ValueError with consistent message."""
		logger.warning("LLM response validation failed: %s", message)
		raise ValueError(message)

	try:
		# Handle both direct JSON objects and strings containing JSON
		if not content.strip().startswith("{"):
			# Extract JSON if it's wrapped in other text
			json_match = re.search(r"({.*})", content, re.DOTALL)
			if json_match:
				content = json_match.group(1)

		message_data = json.loads(content)
		logger.debug("Parsed JSON: %s", message_data)

		# Check for simplified {"commit_message": "..."} format
		if "commit_message" in message_data and isinstance(message_data["commit_message"], str):
			return message_data["commit_message"].strip()

		# Check for {"message": "..."} format
		if "message" in message_data and isinstance(message_data["message"], str):
			return message_data["message"].strip()

		# Basic Schema Validation
		if not isinstance(message_data, dict):
			_raise_validation_error("JSON response is not an object")

		if not message_data.get("type") or not message_data.get("description"):
			_raise_validation_error("Missing required fields in JSON response")

		# Extract components with validation/defaults
		commit_type = str(message_data["type"]).lower().strip()

		# Check for valid commit type if config_loader is provided
		if config_loader:
			valid_types = config_loader.get_commit_convention().get("types", [])
			if valid_types and commit_type not in valid_types:
				logger.warning("Invalid commit type: %s. Valid types: %s", commit_type, valid_types)
				# Try to find a valid type as fallback
				if "feat" in valid_types:
					commit_type = "feat"
				elif "fix" in valid_types:
					commit_type = "fix"
				elif len(valid_types) > 0:
					commit_type = valid_types[0]
				logger.debug("Using fallback commit type: %s", commit_type)

		scope = message_data.get("scope")
		if scope is not None:
			scope = str(scope).lower().strip()

		description = str(message_data["description"]).strip()

		# Ensure description doesn't start with another type prefix
		if config_loader:
			valid_types = config_loader.get_commit_convention().get("types", [])
			for valid_type in valid_types:
				if description.lower().startswith(f"{valid_type}:"):
					description = description.split(":", 1)[1].strip()
					break

		body = message_data.get("body")
		if body is not None:
			body = str(body).strip()
		is_breaking = bool(message_data.get("breaking", False))

		# Format the header
		header = f"{commit_type}"
		if scope:
			header += f"({scope})"
		if is_breaking:
			header += "!"
		header += f": {description}"

		# Ensure compliance with commit format
		if ": " not in header:
			parts = header.split(":")
			if len(parts) == 2:  # type+scope and description # noqa: PLR2004
				header = f"{parts[0]}: {parts[1].strip()}"

		# Build the complete message
		message_parts = [header]

		# Add body if provided
		if body:
			message_parts.append("")  # Empty line between header and body
			message_parts.append(body)

		# Handle breaking change footers
		footers = message_data.get("footers", [])
		breaking_change_footers = []

		if isinstance(footers, list):
			breaking_change_footers = [
				footer
				for footer in footers
				if isinstance(footer, dict)
				and footer.get("token", "").upper() in ("BREAKING CHANGE", "BREAKING-CHANGE")
			]

		if breaking_change_footers:
			if not body:
				message_parts.append("")  # Empty line before footers if no body
			else:
				message_parts.append("")  # Empty line between body and footers

			for footer in breaking_change_footers:
				token = footer.get("token", "")
				value = footer.get("value", "")
				message_parts.append(f"{token}: {value}")

		message = "\n".join(message_parts)
		logger.debug("Formatted commit message: %s", message)
		return message

	except (json.JSONDecodeError, ValueError, TypeError, AttributeError) as e:
		# If parsing or validation fails, return the content as-is, but cleaned
		logger.warning("Error formatting JSON to commit message: %s. Using raw content.", str(e))
		return content.strip()

prepare_prompt

prepare_prompt(
	template: str,
	diff_content: str,
	file_info: dict[str, Any],
	convention: dict[str, Any],
	extra_context: dict[str, Any] | None = None,
) -> str

Prepare a prompt for LLM commit message generation.

Parameters:

Name	Type	Description	Default
template	str	The prompt template string	required
diff_content	str	The diff content to include in the prompt	required
file_info	dict[str, Any]	Dictionary of file information	required
convention	dict[str, Any]	Commit convention configuration	required
extra_context	dict[str, Any] | None	Additional context variables for the template	None

Returns:

Type	Description
str	Formatted prompt string

Source code in src/codemap/git/commit_generator/utils.py

def prepare_prompt(
	template: str,
	diff_content: str,
	file_info: dict[str, Any],
	convention: dict[str, Any],
	extra_context: dict[str, Any] | None = None,
) -> str:
	"""
	Prepare a prompt for LLM commit message generation.

	Args:
	        template: The prompt template string
	        diff_content: The diff content to include in the prompt
	        file_info: Dictionary of file information
	        convention: Commit convention configuration
	        extra_context: Additional context variables for the template

	Returns:
	        Formatted prompt string

	"""
	# Create a context dict with default values for template variables
	context = {
		"diff": diff_content,
		"files": file_info,
		"convention": convention,
		"schema": COMMIT_MESSAGE_SCHEMA,
		"original_message": "",  # Default value for original_message
		"lint_errors": "",  # Default value for lint_errors
	}

	# Update with any extra context provided
	if extra_context:
		context.update(extra_context)

	try:
		from string import Template

		template_obj = Template(template)
		return template_obj.safe_substitute(context)
	except (ValueError, KeyError) as e:
		logger.warning("Error formatting prompt template: %s", str(e))
		# Fallback to simple string formatting
		return template.format(**context)

command

Main commit command implementation for CodeMap.

logger module-attribute

logger = getLogger(__name__)

MAX_FILES_BEFORE_BATCHING module-attribute

MAX_FILES_BEFORE_BATCHING = 10

MAX_FILE_CONTENT_LINES module-attribute

MAX_FILE_CONTENT_LINES = 300

MAX_TOTAL_CONTENT_LINES module-attribute

MAX_TOTAL_CONTENT_LINES = 1000

MIN_PORCELAIN_LINE_LENGTH module-attribute

MIN_PORCELAIN_LINE_LENGTH = 3

ExitCommandError

Bases: Exception

Exception to signal an exit command.

Source code in src/codemap/git/commit_generator/command.py

class ExitCommandError(Exception):
	"""Exception to signal an exit command."""

CommitCommand

Handles the commit command workflow.

Source code in src/codemap/git/commit_generator/command.py

class CommitCommand:
	"""Handles the commit command workflow."""

	def __init__(self, path: Path | None = None, model: str = "gpt-4o-mini", bypass_hooks: bool = False) -> None:
		"""
		Initialize the commit command.

		Args:
		    path: Optional path to start from
		    model: LLM model to use for commit message generation
		    bypass_hooks: Whether to bypass git hooks with --no-verify

		"""
		try:
			self.repo_root = get_repo_root(path)
			self.ui: CommitUI = CommitUI()
			self.splitter = DiffSplitter(self.repo_root)
			self.target_files = []  # Initialize target_files attribute

			# Store the current branch at initialization to ensure we don't switch branches unexpectedly
			try:
				self.original_branch = get_current_branch()
			except (ImportError, GitError):
				self.original_branch = None

			# Create LLM client and configs
			from codemap.llm import create_client
			from codemap.utils.config_loader import ConfigLoader

			config_loader = ConfigLoader(repo_root=self.repo_root)
			llm_client = create_client(repo_path=self.repo_root, model=model)

			# Create the commit message generator with required parameters
			self.message_generator = CommitMessageGenerator(
				repo_root=self.repo_root,
				llm_client=llm_client,
				prompt_template=DEFAULT_PROMPT_TEMPLATE,
				config_loader=config_loader,
			)

			self.error_state = None  # Tracks reason for failure: "failed", "aborted", etc.
			self.bypass_hooks = bypass_hooks  # Whether to bypass git hooks with --no-verify
		except GitError as e:
			raise RuntimeError(str(e)) from e

	def _get_changes(self) -> list[GitDiff]:
		"""
		Get staged, unstaged, and untracked changes, generating a GitDiff object per file.

		Returns:
		    List of GitDiff objects, each representing changes for a single file.

		Raises:
		    RuntimeError: If Git operations fail.

		"""
		changes: list[GitDiff] = []
		processed_files: set[str] = set()  # Track files already added

		try:
			# 1. Get Staged Changes (Per File)
			staged_files = run_git_command(["git", "diff", "--cached", "--name-only"]).splitlines()
			if staged_files:
				logger.debug("Found %d staged files. Fetching diffs individually...", len(staged_files))
				for file_path in staged_files:
					if file_path in processed_files:
						continue  # Avoid duplicates if somehow listed again
					try:
						file_diff_content = run_git_command(["git", "diff", "--cached", "--", file_path])
						changes.append(GitDiff(files=[file_path], content=file_diff_content, is_staged=True))
						processed_files.add(file_path)
					except GitError as e:
						logger.warning("Could not get staged diff for %s: %s", file_path, e)

			# 2. Get Unstaged Changes (Per File for files not already staged)
			unstaged_files = run_git_command(["git", "diff", "--name-only"]).splitlines()
			if unstaged_files:
				logger.debug("Found %d unstaged files. Fetching diffs individually...", len(unstaged_files))
				for file_path in unstaged_files:
					# Only process unstaged if not already captured as staged
					if file_path not in processed_files:
						try:
							file_diff_content = run_git_command(["git", "diff", "--", file_path])
							changes.append(GitDiff(files=[file_path], content=file_diff_content, is_staged=False))
							processed_files.add(file_path)
						except GitError as e:
							logger.warning("Could not get unstaged diff for %s: %s", file_path, e)

			# 3. Get Untracked Files (Per File, content formatted as diff)
			untracked_files_paths = get_untracked_files()
			if untracked_files_paths:
				logger.debug("Found %d untracked files. Reading content...", len(untracked_files_paths))
				total_content_lines = 0

				for file_path in untracked_files_paths:
					# Only process untracked if not already captured as staged/unstaged (edge case)
					if file_path not in processed_files:
						abs_path = self.repo_root / file_path
						try:
							content = read_file_content(abs_path)
							if content is not None:
								content_lines = content.splitlines()
								original_line_count = len(content_lines)
								needs_total_truncation_notice = False

								# File-level truncation
								if len(content_lines) > MAX_FILE_CONTENT_LINES:
									logger.info(
										"Untracked file %s is large (%d lines), truncating to %d lines",
										file_path,
										len(content_lines),
										MAX_FILE_CONTENT_LINES,
									)
									truncation_msg = (
										f"[... {len(content_lines) - MAX_FILE_CONTENT_LINES} more lines truncated ...]"
									)
									content_lines = content_lines[:MAX_FILE_CONTENT_LINES]
									content_lines.append(truncation_msg)

								# Total content truncation check
								if total_content_lines + len(content_lines) > MAX_TOTAL_CONTENT_LINES:
									remaining_lines = MAX_TOTAL_CONTENT_LINES - total_content_lines
									if remaining_lines > 0:
										logger.info(
											"Total untracked content size exceeded limit. Truncating %s to %d lines",
											file_path,
											remaining_lines,
										)
										content_lines = content_lines[:remaining_lines]
										needs_total_truncation_notice = True
									else:
										# No space left at all, skip this file and subsequent ones
										logger.warning(
											"Max total untracked lines reached. Skipping remaining untracked files."
										)
										break

								# Format content for the diff
								formatted_content = ["--- /dev/null", f"+++ b/{file_path}"]
								formatted_content.extend(f"+{line}" for line in content_lines)
								if needs_total_truncation_notice:
									formatted_content.append(
										"+[... Further untracked files truncated due to total size limits ...]"
									)

								file_content_str = "\n".join(formatted_content)
								changes.append(
									GitDiff(
										files=[file_path], content=file_content_str, is_staged=False, is_untracked=True
									)
								)
								total_content_lines += len(content_lines)
								processed_files.add(file_path)
								logger.debug(
									"Added content for untracked file %s (%d lines / %d original).",
									file_path,
									len(content_lines),
									original_line_count,
								)
							else:
								# File content is None or empty
								logger.warning(
									"Untracked file %s could not be read or is empty. Creating entry without content.",
									file_path,
								)
								changes.append(
									GitDiff(files=[file_path], content="", is_staged=False, is_untracked=True)
								)
								processed_files.add(file_path)
						except (OSError, UnicodeDecodeError) as file_read_error:
							logger.warning(
								"Could not read untracked file %s: %s. Creating entry without content.",
								file_path,
								file_read_error,
							)
							changes.append(GitDiff(files=[file_path], content="", is_staged=False, is_untracked=True))
							processed_files.add(file_path)

		except GitError as e:
			msg = f"Failed to get repository changes: {e}"
			logger.exception(msg)
			raise RuntimeError(msg) from e

		return changes

	def _perform_commit(self, chunk: DiffChunk, message: str) -> bool:
		"""
		Perform the actual commit operation.

		Args:
		    chunk: The chunk to commit
		    message: Commit message to use

		Returns:
		    True if successful, False otherwise

		"""
		try:
			# Commit only the files specified in the chunk
			commit_only_files(chunk.files, message, ignore_hooks=self.bypass_hooks)
			self.ui.show_success(f"Committed {len(chunk.files)} files.")
			return True
		except GitError as e:
			error_msg = f"Error during commit: {e}"
			self.ui.show_error(error_msg)
			logger.exception(error_msg)
			self.error_state = "failed"
			return False

	def _process_chunk(self, chunk: DiffChunk, index: int, total_chunks: int) -> bool:
		"""
		Process a single chunk interactively.

		Args:
		    chunk: DiffChunk to process
		    index: The 0-based index of the current chunk
		    total_chunks: The total number of chunks

		Returns:
		    True if processing should continue, False to abort or on failure.

		Raises:
		    typer.Exit: If user chooses to exit.

		"""
		logger.debug(
			"Processing chunk - Chunk ID: %s, Index: %d/%d, Files: %s",
			id(chunk),
			index + 1,
			total_chunks,
			chunk.files,
		)

		# Clear previous generation state if any
		chunk.description = None
		chunk.is_llm_generated = False

		while True:  # Loop to allow regeneration/editing
			message = ""
			used_llm = False
			passed_linting = True  # Assume true unless linting happens and fails
			lint_messages: list[str] = []  # Initialize lint messages list

			# Generate message (potentially with linting retries)
			try:
				# Generate message using the updated method
				message, used_llm, passed_linting, lint_messages = self.message_generator.generate_message_with_linting(
					chunk
				)
				chunk.description = message
				chunk.is_llm_generated = used_llm
			except (LLMError, RuntimeError) as e:
				logger.exception("Failed during message generation for chunk")
				self.ui.show_error(f"Error generating message: {e}")
				# Offer to skip or exit after generation error
				if not questionary.confirm("Skip this chunk and continue?", default=True).ask():
					self.error_state = "aborted"
					return False  # Abort
				# If user chooses to skip after generation error, we continue to the next chunk
				return True

			# -------- Handle Linting Result and User Action ---------
			if not passed_linting:
				# Display the diff chunk info first
				self.ui.display_chunk(chunk, index, total_chunks)
				# Display the failed message and lint errors
				self.ui.display_failed_lint_message(message, lint_messages, used_llm)
				# Ask user what to do on failure
				action = self.ui.get_user_action_on_lint_failure()
			else:
				# Display the valid message and diff chunk
				self.ui.display_chunk(chunk, index, total_chunks)  # Pass correct index and total
				# Ask user what to do with the valid message
				action = self.ui.get_user_action()

			# -------- Process User Action ---------
			if action == ChunkAction.COMMIT:
				# Commit with the current message (which is valid if we got here via the 'else' block)
				if self._perform_commit(chunk, message):
					return True  # Continue to next chunk
				self.error_state = "failed"
				return False  # Abort on commit failure
			if action == ChunkAction.EDIT:
				# Allow user to edit the message
				current_message = chunk.description or ""  # Default to empty string if None
				edited_message = self.ui.edit_message(current_message)
				cleaned_edited_message = clean_message_for_linting(edited_message)
				edited_is_valid, _ = lint_commit_message(cleaned_edited_message)
				# Convert error_message to list for compatibility with the rest of the code
				if edited_is_valid:
					# Commit with the user-edited, now valid message
					if self._perform_commit(chunk, cleaned_edited_message):
						return True  # Continue to next chunk
					self.error_state = "failed"
					return False  # Abort on commit failure
				# If edited message is still invalid, show errors and loop back
				self.ui.show_warning("Edited message still failed linting.")
				# Update state for the next loop iteration to show the edited (but invalid) message
				chunk.description = edited_message
				chunk.is_llm_generated = False  # Mark as not LLM-generated
				continue  # Go back to the start of the while loop
			if action == ChunkAction.REGENERATE:
				self.ui.show_regenerating()
				chunk.description = None  # Clear description before regenerating
				chunk.is_llm_generated = False
				continue  # Go back to the start of the while loop to regenerate
			if action == ChunkAction.SKIP:
				self.ui.show_skipped(chunk.files)
				return True  # Continue to next chunk
			if action == ChunkAction.EXIT:
				if self.ui.confirm_exit():
					self.error_state = "aborted"
					# Returning False signals to stop processing chunks
					return False
				# If user cancels exit, loop back to show the chunk again
				continue

			# Should not be reached
			logger.error("Unhandled action in _process_chunk: %s", action)
			return False

	def process_all_chunks(self, chunks: list[DiffChunk], grand_total: int, interactive: bool = True) -> bool:
		"""
		Process all generated chunks.

		Args:
		    chunks: List of DiffChunk objects to process
		    grand_total: Total number of chunks initially generated
		    interactive: Whether to run in interactive mode

		Returns:
		    True if all chunks were processed successfully, False otherwise

		"""
		if not chunks:
			self.ui.show_error("No diff chunks found to process.")
			return False

		success = True
		for i, chunk in enumerate(chunks):
			if interactive:
				try:
					if not self._process_chunk(chunk, i, grand_total):
						success = False
						break
				except typer.Exit:
					# User chose to exit via typer.Exit(), which is expected
					success = False  # Indicate not all chunks were processed
					break
				except RuntimeError as e:
					self.ui.show_error(f"Runtime error processing chunk: {e}")
					success = False
					break
			else:
				# Non-interactive mode: generate and attempt commit
				try:
					message, _, passed_linting, _ = self.message_generator.generate_message_with_linting(chunk)
					if not passed_linting:
						logger.warning("Generated message failed linting in non-interactive mode: %s", message)
						# Decide behavior: skip, commit anyway, fail? Let's skip for now.
						self.ui.show_skipped(chunk.files)
						continue
					if not self._perform_commit(chunk, message):
						success = False
						break
				except (LLMError, RuntimeError, GitError) as e:
					self.ui.show_error(f"Error processing chunk non-interactively: {e}")
					success = False
					break

		return success

	def run(self, interactive: bool = True) -> bool:
		"""
		Run the commit command workflow.

		Args:
		    interactive: Whether to run in interactive mode. Defaults to True.

		Returns:
		    True if the process completed (even if aborted), False on unexpected error.

		"""
		try:
			with loading_spinner("Analyzing changes..."):
				changes = self._get_changes()

			if not changes:
				self.ui.show_message("No changes detected to commit.")
				return True

			# Process each diff separately to avoid parsing issues
			chunks = []

			for diff in changes:
				# Process each diff individually
				diff_chunks, _ = self.splitter.split_diff(diff)
				chunks.extend(diff_chunks)

			total_chunks = len(chunks)
			logger.info("Split files into %d chunks.", total_chunks)

			if not chunks:
				# Import DiffChunk for clarity

				# If no target files available, try to detect modified files
				if not self.target_files:
					try:
						# Get staged files
						staged_output = run_git_command(["git", "diff", "--cached", "--name-only"])
						if staged_output.strip():
							self.target_files.extend(staged_output.splitlines())

						# Get unstaged but tracked files
						unstaged_output = run_git_command(["git", "diff", "--name-only"])
						if unstaged_output.strip():
							self.target_files.extend(unstaged_output.splitlines())

						# Get untracked files
						untracked_files = get_untracked_files()
						if untracked_files:
							self.target_files.extend(untracked_files)

						# Remove duplicates
						self.target_files = list(set(self.target_files))

						if self.target_files:
							logger.info(f"Using detected modified files: {self.target_files}")
					except GitError as e:
						logger.warning(f"Error while getting modified files: {e}")

				# Use helper method to create fallback chunks
				chunks = self._try_create_fallback_chunks(self.target_files)

				# If still no chunks, return error
				if not chunks:
					self.ui.show_error("Failed to split changes into manageable chunks.")
					return False

			# Process chunks, passing the interactive flag
			success = self.process_all_chunks(chunks, total_chunks, interactive=interactive)

			if self.error_state == "aborted":
				self.ui.show_message("Commit process aborted by user.")
				return True  # Abort is considered a valid exit
			if self.error_state == "failed":
				self.ui.show_error("Commit process failed due to errors.")
				return False
			if not success:
				# If process_all_chunks returned False without setting error_state
				self.ui.show_error("Commit process failed.")
				return False
			self.ui.show_all_done()
			return True

		except RuntimeError as e:
			self.ui.show_error(str(e))
			return False
		except Exception as e:
			self.ui.show_error(f"An unexpected error occurred: {e}")
			logger.exception("Unexpected error in commit command run loop")
			return False
		finally:
			# Restore original branch if it was changed
			if self.original_branch:
				try:
					# get_current_branch is already imported
					# switch_branch is imported from codemap.git.utils now
					current = get_current_branch()
					if current != self.original_branch:
						logger.info("Restoring original branch: %s", self.original_branch)
						switch_branch(self.original_branch)
				except (GitError, Exception) as e:
					logger.warning("Could not restore original branch %s: %s", self.original_branch, e)

	def _try_create_fallback_chunks(self, files: list[str]) -> list[DiffChunk]:
		"""
		Try to create fallback chunks for files when regular splitting fails.

		Args:
			files: List of file paths to process

		Returns:
			List of created DiffChunk objects
		"""
		from codemap.git.diff_splitter import DiffChunk

		chunks = []

		# Get all tracked files from git
		try:
			all_tracked_files = run_git_command(["git", "ls-files"]).splitlines()

			# If files has incorrect paths (e.g., "rc/" instead of "src/"), attempt to fix them
			corrected_files = []
			for file in files:
				# Check if file exists as is
				if file in all_tracked_files:
					corrected_files.append(file)
					continue

				# Try to find a similar file in tracked files
				if file.startswith("rc/") and file.replace("rc/", "src/") in all_tracked_files:
					corrected_file = file.replace("rc/", "src/")
					logger.info(f"Corrected file path from {file} to {corrected_file}")
					corrected_files.append(corrected_file)
					continue

				# Add other potential corrections here
				# For example, check for case-insensitive matches

				logger.warning(f"Could not find a matching tracked file for {file}")

			# Update files with corrected paths if needed
			if corrected_files:
				files = corrected_files
				logger.info(f"Using corrected file paths: {files}")

			# Now try to create chunks with the corrected paths
			for file in files:
				try:
					# Try unstaged changes first
					file_diff = run_git_command(["git", "diff", "HEAD", "--", file])
					if file_diff.strip():
						logger.debug(f"Created individual chunk for {file}")
						chunks.append(DiffChunk(files=[file], content=file_diff))
						continue  # Skip to next file if we found a diff

					# Then try staged changes
					file_diff = run_git_command(["git", "diff", "--cached", "--", file])
					if file_diff.strip():
						logger.debug(f"Created individual chunk for staged {file}")
						chunks.append(DiffChunk(files=[file], content=file_diff))
				except GitError:
					logger.warning(f"Could not get diff for {file}")
		except GitError as e:
			logger.warning(f"Error while trying to fix file paths: {e}")

		# If still no chunks but we have files, create empty chunks as last resort
		if not chunks and files:
			logger.warning("No diffs found, creating minimal placeholder chunks")
			for file in files:
				# Create a minimal diff just to allow the process to continue
				placeholder_diff = f"--- a/{file}\n+++ b/{file}\n@@ -1 +1 @@\n No content change detected"
				chunks.append(DiffChunk(files=[file], content=placeholder_diff))
				logger.debug(f"Created placeholder chunk for {file}")

		return chunks

__init__

__init__(
	path: Path | None = None,
	model: str = "gpt-4o-mini",
	bypass_hooks: bool = False,
) -> None

Initialize the commit command.

Parameters:

Name	Type	Description	Default
path	Path | None	Optional path to start from	None
model	str	LLM model to use for commit message generation	'gpt-4o-mini'
bypass_hooks	bool	Whether to bypass git hooks with --no-verify	False

Source code in src/codemap/git/commit_generator/command.py

def __init__(self, path: Path | None = None, model: str = "gpt-4o-mini", bypass_hooks: bool = False) -> None:
	"""
	Initialize the commit command.

	Args:
	    path: Optional path to start from
	    model: LLM model to use for commit message generation
	    bypass_hooks: Whether to bypass git hooks with --no-verify

	"""
	try:
		self.repo_root = get_repo_root(path)
		self.ui: CommitUI = CommitUI()
		self.splitter = DiffSplitter(self.repo_root)
		self.target_files = []  # Initialize target_files attribute

		# Store the current branch at initialization to ensure we don't switch branches unexpectedly
		try:
			self.original_branch = get_current_branch()
		except (ImportError, GitError):
			self.original_branch = None

		# Create LLM client and configs
		from codemap.llm import create_client
		from codemap.utils.config_loader import ConfigLoader

		config_loader = ConfigLoader(repo_root=self.repo_root)
		llm_client = create_client(repo_path=self.repo_root, model=model)

		# Create the commit message generator with required parameters
		self.message_generator = CommitMessageGenerator(
			repo_root=self.repo_root,
			llm_client=llm_client,
			prompt_template=DEFAULT_PROMPT_TEMPLATE,
			config_loader=config_loader,
		)

		self.error_state = None  # Tracks reason for failure: "failed", "aborted", etc.
		self.bypass_hooks = bypass_hooks  # Whether to bypass git hooks with --no-verify
	except GitError as e:
		raise RuntimeError(str(e)) from e

repo_root instance-attribute

repo_root = get_repo_root(path)

ui instance-attribute

ui: CommitUI = CommitUI()

splitter instance-attribute

splitter = DiffSplitter(repo_root)

target_files instance-attribute

target_files = []

original_branch instance-attribute

original_branch = get_current_branch()

message_generator instance-attribute

message_generator = CommitMessageGenerator(
	repo_root=repo_root,
	llm_client=llm_client,
	prompt_template=DEFAULT_PROMPT_TEMPLATE,
	config_loader=config_loader,
)

error_state instance-attribute

error_state = None

bypass_hooks instance-attribute

bypass_hooks = bypass_hooks

process_all_chunks

process_all_chunks(
	chunks: list[DiffChunk],
	grand_total: int,
	interactive: bool = True,
) -> bool

Process all generated chunks.

Parameters:

Name	Type	Description	Default
chunks	list[DiffChunk]	List of DiffChunk objects to process	required
grand_total	int	Total number of chunks initially generated	required
interactive	bool	Whether to run in interactive mode	True

Returns:

Type	Description
bool	True if all chunks were processed successfully, False otherwise

Source code in src/codemap/git/commit_generator/command.py

def process_all_chunks(self, chunks: list[DiffChunk], grand_total: int, interactive: bool = True) -> bool:
	"""
	Process all generated chunks.

	Args:
	    chunks: List of DiffChunk objects to process
	    grand_total: Total number of chunks initially generated
	    interactive: Whether to run in interactive mode

	Returns:
	    True if all chunks were processed successfully, False otherwise

	"""
	if not chunks:
		self.ui.show_error("No diff chunks found to process.")
		return False

	success = True
	for i, chunk in enumerate(chunks):
		if interactive:
			try:
				if not self._process_chunk(chunk, i, grand_total):
					success = False
					break
			except typer.Exit:
				# User chose to exit via typer.Exit(), which is expected
				success = False  # Indicate not all chunks were processed
				break
			except RuntimeError as e:
				self.ui.show_error(f"Runtime error processing chunk: {e}")
				success = False
				break
		else:
			# Non-interactive mode: generate and attempt commit
			try:
				message, _, passed_linting, _ = self.message_generator.generate_message_with_linting(chunk)
				if not passed_linting:
					logger.warning("Generated message failed linting in non-interactive mode: %s", message)
					# Decide behavior: skip, commit anyway, fail? Let's skip for now.
					self.ui.show_skipped(chunk.files)
					continue
				if not self._perform_commit(chunk, message):
					success = False
					break
			except (LLMError, RuntimeError, GitError) as e:
				self.ui.show_error(f"Error processing chunk non-interactively: {e}")
				success = False
				break

	return success

run

run(interactive: bool = True) -> bool

Run the commit command workflow.

Parameters:

Name	Type	Description	Default
interactive	bool	Whether to run in interactive mode. Defaults to True.	True

Returns:

Type	Description
bool	True if the process completed (even if aborted), False on unexpected error.

Source code in src/codemap/git/commit_generator/command.py

def run(self, interactive: bool = True) -> bool:
	"""
	Run the commit command workflow.

	Args:
	    interactive: Whether to run in interactive mode. Defaults to True.

	Returns:
	    True if the process completed (even if aborted), False on unexpected error.

	"""
	try:
		with loading_spinner("Analyzing changes..."):
			changes = self._get_changes()

		if not changes:
			self.ui.show_message("No changes detected to commit.")
			return True

		# Process each diff separately to avoid parsing issues
		chunks = []

		for diff in changes:
			# Process each diff individually
			diff_chunks, _ = self.splitter.split_diff(diff)
			chunks.extend(diff_chunks)

		total_chunks = len(chunks)
		logger.info("Split files into %d chunks.", total_chunks)

		if not chunks:
			# Import DiffChunk for clarity

			# If no target files available, try to detect modified files
			if not self.target_files:
				try:
					# Get staged files
					staged_output = run_git_command(["git", "diff", "--cached", "--name-only"])
					if staged_output.strip():
						self.target_files.extend(staged_output.splitlines())

					# Get unstaged but tracked files
					unstaged_output = run_git_command(["git", "diff", "--name-only"])
					if unstaged_output.strip():
						self.target_files.extend(unstaged_output.splitlines())

					# Get untracked files
					untracked_files = get_untracked_files()
					if untracked_files:
						self.target_files.extend(untracked_files)

					# Remove duplicates
					self.target_files = list(set(self.target_files))

					if self.target_files:
						logger.info(f"Using detected modified files: {self.target_files}")
				except GitError as e:
					logger.warning(f"Error while getting modified files: {e}")

			# Use helper method to create fallback chunks
			chunks = self._try_create_fallback_chunks(self.target_files)

			# If still no chunks, return error
			if not chunks:
				self.ui.show_error("Failed to split changes into manageable chunks.")
				return False

		# Process chunks, passing the interactive flag
		success = self.process_all_chunks(chunks, total_chunks, interactive=interactive)

		if self.error_state == "aborted":
			self.ui.show_message("Commit process aborted by user.")
			return True  # Abort is considered a valid exit
		if self.error_state == "failed":
			self.ui.show_error("Commit process failed due to errors.")
			return False
		if not success:
			# If process_all_chunks returned False without setting error_state
			self.ui.show_error("Commit process failed.")
			return False
		self.ui.show_all_done()
		return True

	except RuntimeError as e:
		self.ui.show_error(str(e))
		return False
	except Exception as e:
		self.ui.show_error(f"An unexpected error occurred: {e}")
		logger.exception("Unexpected error in commit command run loop")
		return False
	finally:
		# Restore original branch if it was changed
		if self.original_branch:
			try:
				# get_current_branch is already imported
				# switch_branch is imported from codemap.git.utils now
				current = get_current_branch()
				if current != self.original_branch:
					logger.info("Restoring original branch: %s", self.original_branch)
					switch_branch(self.original_branch)
			except (GitError, Exception) as e:
				logger.warning("Could not restore original branch %s: %s", self.original_branch, e)

SemanticCommitCommand

Bases: CommitCommand

Handles the semantic commit command workflow.

Source code in src/codemap/git/commit_generator/command.py

class SemanticCommitCommand(CommitCommand):
	"""Handles the semantic commit command workflow."""

	def __init__(
		self,
		path: Path | None = None,
		model: str = "gpt-4o-mini",
		bypass_hooks: bool = False,
		embedding_model: str = "all-MiniLM-L6-v2",
		clustering_method: str = "agglomerative",
		similarity_threshold: float = 0.6,
	) -> None:
		"""
		Initialize the semantic commit command.

		Args:
		        path: Optional path to start from
		        model: LLM model to use for commit message generation
		        bypass_hooks: Whether to bypass git hooks with --no-verify
		        embedding_model: Model to use for generating embeddings
		        clustering_method: Method to use for clustering ("agglomerative" or "dbscan")
		        similarity_threshold: Threshold for group similarity to trigger merging

		"""
		super().__init__(path, model, bypass_hooks)

		# Import semantic grouping components
		from codemap.git.semantic_grouping.clusterer import DiffClusterer
		from codemap.git.semantic_grouping.embedder import DiffEmbedder
		from codemap.git.semantic_grouping.resolver import FileIntegrityResolver

		# Initialize semantic grouping components
		self.embedder = DiffEmbedder(model_name=embedding_model)
		self.clusterer = DiffClusterer(method=clustering_method)
		self.resolver = FileIntegrityResolver(similarity_threshold=similarity_threshold)

		# Track state for commits
		self.committed_files: set[str] = set()
		self.is_pathspec_mode = False
		self.all_repo_files: set[str] = set()
		self.target_files: list[str] = []

	def _get_target_files(self, pathspecs: list[str] | None = None) -> list[str]:
		"""
		Get the list of target files based on pathspecs.

		Args:
		        pathspecs: Optional list of path specifications

		Returns:
		        List of file paths

		"""
		try:
			cmd = ["git", "status", "--porcelain=v1", "-uall"]
			if pathspecs:
				cmd.extend(["--", *pathspecs])
				self.is_pathspec_mode = True

			output = run_git_command(cmd)

			# Parse porcelain output to get file paths
			target_files = []
			for line in output.splitlines():
				if not line or len(line) < MIN_PORCELAIN_LINE_LENGTH:
					continue

				status = line[:2]
				file_path = line[3:].strip()

				# Handle renamed files
				if status.startswith("R"):
					# Extract the new file name after the arrow
					file_path = file_path.split(" -> ")[1]

				target_files.append(file_path)

			# If in pathspec mode, get all repo files for later use
			if self.is_pathspec_mode:
				self.all_repo_files = set(run_git_command(["git", "ls-files"]).splitlines())

			return target_files

		except GitError as e:
			msg = f"Failed to get target files: {e}"
			logger.exception(msg)
			raise RuntimeError(msg) from e

	def _prepare_untracked_files(self, target_files: list[str]) -> list[str]:
		"""
		Prepare untracked files for diffing by adding them to the index.

		Args:
		        target_files: List of target file paths

		Returns:
		        List of untracked files that were prepared

		"""
		try:
			# Get untracked files
			untracked_files = get_untracked_files()

			# Filter to only those in target_files
			untracked_targets = [f for f in untracked_files if f in target_files]

			if untracked_targets:
				# Add untracked files to the index (but not staging area)
				run_git_command(["git", "add", "-N", "--", *untracked_targets])

			return untracked_targets

		except GitError as e:
			logger.warning("Error preparing untracked files: %s", e)
			return []

	def _get_combined_diff(self, target_files: list[str]) -> GitDiff:
		"""
		Get the combined diff for all target files.

		Args:
		        target_files: List of target file paths

		Returns:
		        GitDiff object with the combined diff

		"""
		try:
			# Get diff against HEAD for all target files
			diff_content = run_git_command(["git", "diff", "HEAD", "--", *target_files])

			return GitDiff(files=target_files, content=diff_content)

		except GitError as e:
			msg = f"Failed to get combined diff: {e}"
			logger.exception(msg)
			raise RuntimeError(msg) from e

	def _create_semantic_groups(self, chunks: list[DiffChunk]) -> list[SemanticGroup]:
		"""
		Create semantic groups from diff chunks.

		Args:
		        chunks: List of DiffChunk objects

		Returns:
		        List of SemanticGroup objects

		"""
		# Shortcut for small changes - bypass embedding process
		if len(chunks) <= 3:  # Threshold for "small changes" # noqa: PLR2004
			logger.info("Small number of chunks detected (%d), bypassing embedding process", len(chunks))
			# Create a single semantic group with all chunks
			single_group = SemanticGroup(chunks=chunks)
			# Extract all file names from chunks
			files_set = set()
			for chunk in chunks:
				files_set.update(chunk.files)
			single_group.files = list(files_set)
			# Combine all content
			combined_content = "\n".join(chunk.content for chunk in chunks)
			single_group.content = combined_content
			return [single_group]

		# Generate embeddings for chunks
		chunk_embedding_tuples = self.embedder.embed_chunks(chunks)
		chunk_embeddings = {ce[0]: ce[1] for ce in chunk_embedding_tuples}

		# Cluster chunks
		cluster_lists = self.clusterer.cluster(chunk_embedding_tuples)

		# Create initial semantic groups
		initial_groups = [SemanticGroup(chunks=cluster) for cluster in cluster_lists]

		# Resolve file integrity constraints
		return self.resolver.resolve_violations(initial_groups, chunk_embeddings)

	def _generate_group_messages(self, groups: list[SemanticGroup]) -> list[SemanticGroup]:
		"""
		Generate commit messages for semantic groups.

		Args:
		        groups: List of SemanticGroup objects

		Returns:
		        List of SemanticGroup objects with messages

		"""
		from codemap.git.semantic_grouping.batch_processor import batch_generate_messages

		# Get config loader and settings
		config_loader = self.message_generator.get_config_loader()
		llm_config = config_loader.get("llm", {})
		use_batch_processing = llm_config.get("use_batch_processing", True)
		model = llm_config.get("model", "openai/gpt-4o-mini")

		# Handle batch processing if enabled and we have multiple groups
		if use_batch_processing and len(groups) > 1:
			try:
				logger.info(f"Using batch processing for {len(groups)} semantic groups")
				# Get the prompt template from the message generator
				prompt_template = self.message_generator.prompt_template

				# Run the batch processing
				return batch_generate_messages(
					groups=groups, prompt_template=prompt_template, config_loader=config_loader, model=model
				)
			except Exception:
				logger.exception("Batch processing failed")
				# Show warning message in UI when falling back
				self.ui.show_warning("Batch processing failed. Falling back to individual message generation.")
				logger.info("Falling back to individual message generation")
				# Fall back to individual message generation

		# Process groups individually
		from codemap.git.diff_splitter import DiffChunk
		from codemap.git.semantic_grouping.context_processor import process_chunks_with_lod

		# Get max token limit and settings from message generator's config
		max_tokens = llm_config.get("max_context_tokens", 4000)
		use_lod_context = llm_config.get("use_lod_context", True)

		for group in groups:
			try:
				# Create temporary DiffChunks from the group's chunks
				if use_lod_context and len(group.chunks) > 1:
					logger.debug("Processing semantic group with %d chunks using LOD context", len(group.chunks))
					try:
						# Process all chunks in the group with LOD context processor
						optimized_content = process_chunks_with_lod(group.chunks, max_tokens)

						if optimized_content:
							# Create a temporary chunk with the optimized content
							temp_chunk = DiffChunk(files=group.files, content=optimized_content)
						else:
							# Fallback: create a temp chunk with original content
							temp_chunk = DiffChunk(files=group.files, content=group.content)
					except Exception:
						logger.exception("Error in LOD context processing")
						# Fallback to original content
						temp_chunk = DiffChunk(files=group.files, content=group.content)
				else:
					# Use the original group content
					temp_chunk = DiffChunk(files=group.files, content=group.content)

				# Generate message with linting
				# We ignore linting status - SemanticCommitCommand is less strict
				message, _, _, _ = self.message_generator.generate_message_with_linting(temp_chunk)

				# Store the message with the group
				group.message = message

			except Exception:
				logger.exception("Error generating message for group")
				# Use a fallback message
				group.message = f"update: changes to {len(group.files)} files"

		return groups

	def _stage_and_commit_group(self, group: SemanticGroup) -> bool:
		"""
		Stage and commit a semantic group.

		Args:
		        group: SemanticGroup to commit

		Returns:
		        bool: Whether the commit was successful

		"""
		# Get files in this group
		group_files = group.files

		try:
			# First, unstage any previously staged files
			# This ensures we only commit the current group
			run_git_command(["git", "reset"])

			# Add the group files to the index
			run_git_command(["git", "add", "--", *group_files])

			# Create the commit with the group message
			commit_cmd = ["git", "commit", "-m", group.message or ""]

			# Add --no-verify if bypass_hooks is set
			if self.bypass_hooks:
				commit_cmd.append("--no-verify")

			try:
				run_git_command(commit_cmd)

				# Mark files as committed
				self.committed_files.update(group_files)
				return True
			except GitError as commit_error:
				# Check if this is a pre-commit hook failure
				if "pre-commit" in str(commit_error) and not self.bypass_hooks:
					# Show the error message for clarity
					error_msg = str(commit_error)
					if "conventional commit" in error_msg.lower() or "lint" in error_msg.lower():
						# Extract the lint errors if possible
						lint_errors = [
							line.strip()
							for line in error_msg.splitlines()
							if line.strip() and not line.startswith("Command") and "returned non-zero" not in line
						]

						# Show the message with lint warnings
						message = group.message or ""  # Use empty string if None
						self.ui.display_failed_lint_message(message, lint_errors, is_llm_generated=True)

						# Present options specific to lint failures
						lint_action = self.ui.get_user_action_on_lint_failure()

						if lint_action == ChunkAction.REGENERATE:
							self.ui.show_regenerating()
							try:
								# Create temporary DiffChunk for regeneration
								from codemap.git.diff_splitter import DiffChunk

								temp_chunk = DiffChunk(files=group.files, content=group.content)

								# Use the linting-aware prompt this time
								message, _, _, _ = self.message_generator.generate_message_with_linting(temp_chunk)
								group.message = message

								# Try again with the new message
								return self._stage_and_commit_group(group)
							except (LLMError, GitError, RuntimeError) as e:
								self.ui.show_error(f"Error regenerating message: {e}")
								return False
						elif lint_action == ChunkAction.COMMIT:
							# User chose to bypass the linter
							self.ui.show_message("Bypassing linter and committing with --no-verify")
							commit_cmd.append("--no-verify")
							try:
								run_git_command(commit_cmd)
								# Mark files as committed
								self.committed_files.update(group_files)
								return True
							except GitError as e:
								self.ui.show_error(f"Commit failed even with --no-verify: {e}")
								return False
						elif lint_action == ChunkAction.EDIT:
							edited_message = self.ui.edit_message(group.message or "")  # Empty string as fallback
							group.message = edited_message
							return self._stage_and_commit_group(group)
						elif lint_action == ChunkAction.SKIP:
							self.ui.show_skipped(group.files)
							return False
						elif lint_action == ChunkAction.EXIT:
							if self.ui.confirm_exit():
								raise ExitCommandError from None
							return False

					# Generic pre-commit hook failure (not specifically commit message linting)
					hook_action = self.ui.confirm_bypass_hooks()

					if hook_action == ChunkAction.COMMIT:
						# User chose to bypass the hooks
						self.ui.show_message("Bypassing Git hooks and committing with --no-verify")
						commit_cmd.append("--no-verify")
						try:
							run_git_command(commit_cmd)
							# Mark files as committed
							self.committed_files.update(group_files)
							return True
						except GitError as e:
							self.ui.show_error(f"Commit failed even with --no-verify: {e}")
							return False
					elif hook_action == ChunkAction.REGENERATE:
						self.ui.show_regenerating()
						try:
							# Create temporary DiffChunk for regeneration
							from codemap.git.diff_splitter import DiffChunk

							temp_chunk = DiffChunk(files=group.files, content=group.content)

							# Use the linting-aware prompt this time
							message, _, _, _ = self.message_generator.generate_message_with_linting(temp_chunk)
							group.message = message

							# Try again with the new message
							return self._stage_and_commit_group(group)
						except (LLMError, GitError, RuntimeError) as e:
							self.ui.show_error(f"Error regenerating message: {e}")
							return False
					elif hook_action == ChunkAction.EDIT:
						edited_message = self.ui.edit_message(group.message or "")  # Empty string as fallback
						group.message = edited_message
						return self._stage_and_commit_group(group)
					elif hook_action == ChunkAction.SKIP:
						self.ui.show_skipped(group.files)
						return False
					elif hook_action == ChunkAction.EXIT:
						if self.ui.confirm_exit():
							raise ExitCommandError from None
						return False

				# Either not a pre-commit hook error or user declined to bypass
				self.ui.show_error(f"Failed to commit: {commit_error}")
				return False

		except GitError as e:
			self.ui.show_error(f"Git operation failed: {e}")
			return False
		except Exception as e:
			self.ui.show_error(f"Unexpected error during commit: {e}")
			logger.exception("Unexpected error in _stage_and_commit_group")
			return False

	def run(self, interactive: bool = True, pathspecs: list[str] | None = None) -> bool:
		"""
		Run the semantic commit command workflow.

		Args:
		        interactive: Whether to run in interactive mode
		        pathspecs: Optional list of path specifications

		Returns:
		        bool: Whether the process completed successfully

		"""
		committed_count = 0  # Initialize this at the beginning of the method

		try:
			# Get target files
			with loading_spinner("Analyzing repository..."):
				self.target_files = self._get_target_files(pathspecs)

				if not self.target_files:
					self.ui.show_message("No changes detected to commit.")
					return True

				# Prepare untracked files
				self._prepare_untracked_files(self.target_files)

				# Get combined diff
				combined_diff = self._get_combined_diff(self.target_files)

				# Log diff details for debugging
				logger.debug(f"Combined diff size: {len(combined_diff.content)} characters")
				logger.debug(f"Target files: {len(self.target_files)} files")

				# Import DiffChunk before using it
				from codemap.git.diff_splitter import DiffChunk

				# Split diff into chunks
				chunks, _ = self.splitter.split_diff(combined_diff)
				logger.debug(f"Initial chunks created: {len(chunks)}")

				# If no chunks created but we have combined diff content, create a single chunk
				if not chunks and combined_diff.content.strip():
					logger.info("No chunks created from splitter, creating a single chunk")
					chunks = [DiffChunk(files=self.target_files, content=combined_diff.content)]

				# Last resort: try creating individual chunks for each file
				if not chunks:
					logger.info("Attempting to create individual file chunks")
					chunks = self._try_create_fallback_chunks(self.target_files)

				# If still no chunks, return error
				if not chunks:
					self.ui.show_error("Failed to split changes into manageable chunks.")
					return False

				logger.info(f"Final chunk count: {len(chunks)}")

			# Create semantic groups
			with loading_spinner("Creating semantic groups..."):
				# Special case for very few files - create a single group
				if len(chunks) <= 2:  # noqa: PLR2004
					logger.info("Small number of chunks detected, creating a single semantic group")
					# Create a single semantic group with all chunks
					single_group = SemanticGroup(chunks=chunks)
					# Extract all file names from chunks
					files_set = set()
					for chunk in chunks:
						files_set.update(chunk.files)
					single_group.files = list(files_set)
					groups = [single_group]
				else:
					# Normal case - use clustering
					groups = self._create_semantic_groups(chunks)

				if not groups:
					self.ui.show_error("Failed to create semantic groups.")
					return False

				# Generate messages for groups
				groups = self._generate_group_messages(groups)

			# Process groups
			self.ui.show_message(f"Found {len(groups)} semantic groups of changes.")

			success = True

			for i, group in enumerate(groups):
				if interactive:
					# Display group info with improved UI
					self.ui.display_group(group, i, len(groups))

					# Get user action
					action = self.ui.get_group_action()

					if action == ChunkAction.COMMIT:
						self.ui.show_message(f"\nCommitting: {group.message}")
						if self._stage_and_commit_group(group):
							committed_count += 1
						else:
							self.ui.show_error(f"Failed to commit group: {group.message}")
							success = False
					elif action == ChunkAction.EDIT:
						# Allow user to edit the message
						current_message = group.message or ""  # Default to empty string if None
						edited_message = self.ui.edit_message(current_message)
						group.message = edited_message

						# Commit immediately after editing
						self.ui.show_message(f"\nCommitting: {group.message}")
						if self._stage_and_commit_group(group):
							committed_count += 1
						else:
							self.ui.show_error(f"Failed to commit group: {group.message}")
							success = False
					elif action == ChunkAction.REGENERATE:
						self.ui.show_regenerating()
						# Re-generate the message
						try:
							from codemap.git.diff_splitter import DiffChunk

							temp_chunk = DiffChunk(files=group.files, content=group.content)
							message, _, _, _ = self.message_generator.generate_message_with_linting(temp_chunk)
							group.message = message

							# Show the regenerated message
							self.ui.display_group(group, i, len(groups))
							if questionary.confirm("Commit with regenerated message?", default=True).ask():
								self.ui.show_message(f"\nCommitting: {group.message}")
								if self._stage_and_commit_group(group):
									committed_count += 1
								else:
									self.ui.show_error(f"Failed to commit group: {group.message}")
									success = False
							else:
								self.ui.show_skipped(group.files)
						except (LLMError, GitError, RuntimeError) as e:
							self.ui.show_error(f"Error regenerating message: {e}")
							if questionary.confirm("Skip this group?", default=True).ask():
								self.ui.show_skipped(group.files)
							else:
								success = False
					elif action == ChunkAction.SKIP:
						self.ui.show_skipped(group.files)
					elif action == ChunkAction.EXIT and self.ui.confirm_exit():
						# This is a user-initiated exit, should not be considered a failure
						self.ui.show_message("Commit process exited by user.")
						return True  # Return true to indicate normal exit, not failure
				else:
					# In non-interactive mode, commit each group immediately
					group.message = group.message or f"update: changes to {len(group.files)} files"
					self.ui.show_message(f"\nCommitting: {group.message}")
					if self._stage_and_commit_group(group):
						committed_count += 1
					else:
						self.ui.show_error(f"Failed to commit group: {group.message}")
						success = False

			if committed_count > 0:
				self.ui.show_message(f"Successfully committed {committed_count} semantic groups.")
				self.ui.show_all_done()
			else:
				self.ui.show_message("No changes were committed.")

			return success
		except ExitCommandError:
			# User requested to exit during lint failure handling
			return committed_count > 0
		except RuntimeError as e:
			self.ui.show_error(str(e))
			return False
		except Exception as e:
			self.ui.show_error(f"An unexpected error occurred: {e}")
			logger.exception("Unexpected error in semantic commit command")
			return False

__init__

__init__(
	path: Path | None = None,
	model: str = "gpt-4o-mini",
	bypass_hooks: bool = False,
	embedding_model: str = "all-MiniLM-L6-v2",
	clustering_method: str = "agglomerative",
	similarity_threshold: float = 0.6,
) -> None

Initialize the semantic commit command.

Parameters:

Name	Type	Description	Default
path	Path | None	Optional path to start from	None
model	str	LLM model to use for commit message generation	'gpt-4o-mini'
bypass_hooks	bool	Whether to bypass git hooks with --no-verify	False
embedding_model	str	Model to use for generating embeddings	'all-MiniLM-L6-v2'
clustering_method	str	Method to use for clustering ("agglomerative" or "dbscan")	'agglomerative'
similarity_threshold	float	Threshold for group similarity to trigger merging	0.6

Source code in src/codemap/git/commit_generator/command.py

def __init__(
	self,
	path: Path | None = None,
	model: str = "gpt-4o-mini",
	bypass_hooks: bool = False,
	embedding_model: str = "all-MiniLM-L6-v2",
	clustering_method: str = "agglomerative",
	similarity_threshold: float = 0.6,
) -> None:
	"""
	Initialize the semantic commit command.

	Args:
	        path: Optional path to start from
	        model: LLM model to use for commit message generation
	        bypass_hooks: Whether to bypass git hooks with --no-verify
	        embedding_model: Model to use for generating embeddings
	        clustering_method: Method to use for clustering ("agglomerative" or "dbscan")
	        similarity_threshold: Threshold for group similarity to trigger merging

	"""
	super().__init__(path, model, bypass_hooks)

	# Import semantic grouping components
	from codemap.git.semantic_grouping.clusterer import DiffClusterer
	from codemap.git.semantic_grouping.embedder import DiffEmbedder
	from codemap.git.semantic_grouping.resolver import FileIntegrityResolver

	# Initialize semantic grouping components
	self.embedder = DiffEmbedder(model_name=embedding_model)
	self.clusterer = DiffClusterer(method=clustering_method)
	self.resolver = FileIntegrityResolver(similarity_threshold=similarity_threshold)

	# Track state for commits
	self.committed_files: set[str] = set()
	self.is_pathspec_mode = False
	self.all_repo_files: set[str] = set()
	self.target_files: list[str] = []

embedder instance-attribute

embedder = DiffEmbedder(model_name=embedding_model)

clusterer instance-attribute

clusterer = DiffClusterer(method=clustering_method)

resolver instance-attribute

resolver = FileIntegrityResolver(
	similarity_threshold=similarity_threshold
)

committed_files instance-attribute

committed_files: set[str] = set()

is_pathspec_mode instance-attribute

is_pathspec_mode = False

all_repo_files instance-attribute

all_repo_files: set[str] = set()

target_files instance-attribute

target_files: list[str] = []

run

run(
	interactive: bool = True,
	pathspecs: list[str] | None = None,
) -> bool

Run the semantic commit command workflow.

Parameters:

Name	Type	Description	Default
interactive	bool	Whether to run in interactive mode	True
pathspecs	list[str] | None	Optional list of path specifications	None

Returns:

Name	Type	Description
bool	bool	Whether the process completed successfully

Source code in src/codemap/git/commit_generator/command.py

def run(self, interactive: bool = True, pathspecs: list[str] | None = None) -> bool:
	"""
	Run the semantic commit command workflow.

	Args:
	        interactive: Whether to run in interactive mode
	        pathspecs: Optional list of path specifications

	Returns:
	        bool: Whether the process completed successfully

	"""
	committed_count = 0  # Initialize this at the beginning of the method

	try:
		# Get target files
		with loading_spinner("Analyzing repository..."):
			self.target_files = self._get_target_files(pathspecs)

			if not self.target_files:
				self.ui.show_message("No changes detected to commit.")
				return True

			# Prepare untracked files
			self._prepare_untracked_files(self.target_files)

			# Get combined diff
			combined_diff = self._get_combined_diff(self.target_files)

			# Log diff details for debugging
			logger.debug(f"Combined diff size: {len(combined_diff.content)} characters")
			logger.debug(f"Target files: {len(self.target_files)} files")

			# Import DiffChunk before using it
			from codemap.git.diff_splitter import DiffChunk

			# Split diff into chunks
			chunks, _ = self.splitter.split_diff(combined_diff)
			logger.debug(f"Initial chunks created: {len(chunks)}")

			# If no chunks created but we have combined diff content, create a single chunk
			if not chunks and combined_diff.content.strip():
				logger.info("No chunks created from splitter, creating a single chunk")
				chunks = [DiffChunk(files=self.target_files, content=combined_diff.content)]

			# Last resort: try creating individual chunks for each file
			if not chunks:
				logger.info("Attempting to create individual file chunks")
				chunks = self._try_create_fallback_chunks(self.target_files)

			# If still no chunks, return error
			if not chunks:
				self.ui.show_error("Failed to split changes into manageable chunks.")
				return False

			logger.info(f"Final chunk count: {len(chunks)}")

		# Create semantic groups
		with loading_spinner("Creating semantic groups..."):
			# Special case for very few files - create a single group
			if len(chunks) <= 2:  # noqa: PLR2004
				logger.info("Small number of chunks detected, creating a single semantic group")
				# Create a single semantic group with all chunks
				single_group = SemanticGroup(chunks=chunks)
				# Extract all file names from chunks
				files_set = set()
				for chunk in chunks:
					files_set.update(chunk.files)
				single_group.files = list(files_set)
				groups = [single_group]
			else:
				# Normal case - use clustering
				groups = self._create_semantic_groups(chunks)

			if not groups:
				self.ui.show_error("Failed to create semantic groups.")
				return False

			# Generate messages for groups
			groups = self._generate_group_messages(groups)

		# Process groups
		self.ui.show_message(f"Found {len(groups)} semantic groups of changes.")

		success = True

		for i, group in enumerate(groups):
			if interactive:
				# Display group info with improved UI
				self.ui.display_group(group, i, len(groups))

				# Get user action
				action = self.ui.get_group_action()

				if action == ChunkAction.COMMIT:
					self.ui.show_message(f"\nCommitting: {group.message}")
					if self._stage_and_commit_group(group):
						committed_count += 1
					else:
						self.ui.show_error(f"Failed to commit group: {group.message}")
						success = False
				elif action == ChunkAction.EDIT:
					# Allow user to edit the message
					current_message = group.message or ""  # Default to empty string if None
					edited_message = self.ui.edit_message(current_message)
					group.message = edited_message

					# Commit immediately after editing
					self.ui.show_message(f"\nCommitting: {group.message}")
					if self._stage_and_commit_group(group):
						committed_count += 1
					else:
						self.ui.show_error(f"Failed to commit group: {group.message}")
						success = False
				elif action == ChunkAction.REGENERATE:
					self.ui.show_regenerating()
					# Re-generate the message
					try:
						from codemap.git.diff_splitter import DiffChunk

						temp_chunk = DiffChunk(files=group.files, content=group.content)
						message, _, _, _ = self.message_generator.generate_message_with_linting(temp_chunk)
						group.message = message

						# Show the regenerated message
						self.ui.display_group(group, i, len(groups))
						if questionary.confirm("Commit with regenerated message?", default=True).ask():
							self.ui.show_message(f"\nCommitting: {group.message}")
							if self._stage_and_commit_group(group):
								committed_count += 1
							else:
								self.ui.show_error(f"Failed to commit group: {group.message}")
								success = False
						else:
							self.ui.show_skipped(group.files)
					except (LLMError, GitError, RuntimeError) as e:
						self.ui.show_error(f"Error regenerating message: {e}")
						if questionary.confirm("Skip this group?", default=True).ask():
							self.ui.show_skipped(group.files)
						else:
							success = False
				elif action == ChunkAction.SKIP:
					self.ui.show_skipped(group.files)
				elif action == ChunkAction.EXIT and self.ui.confirm_exit():
					# This is a user-initiated exit, should not be considered a failure
					self.ui.show_message("Commit process exited by user.")
					return True  # Return true to indicate normal exit, not failure
			else:
				# In non-interactive mode, commit each group immediately
				group.message = group.message or f"update: changes to {len(group.files)} files"
				self.ui.show_message(f"\nCommitting: {group.message}")
				if self._stage_and_commit_group(group):
					committed_count += 1
				else:
					self.ui.show_error(f"Failed to commit group: {group.message}")
					success = False

		if committed_count > 0:
			self.ui.show_message(f"Successfully committed {committed_count} semantic groups.")
			self.ui.show_all_done()
		else:
			self.ui.show_message("No changes were committed.")

		return success
	except ExitCommandError:
		# User requested to exit during lint failure handling
		return committed_count > 0
	except RuntimeError as e:
		self.ui.show_error(str(e))
		return False
	except Exception as e:
		self.ui.show_error(f"An unexpected error occurred: {e}")
		logger.exception("Unexpected error in semantic commit command")
		return False

generator

Generator module for commit messages.

logger module-attribute

logger = getLogger(__name__)

MAX_DEBUG_CONTENT_LENGTH module-attribute

MAX_DEBUG_CONTENT_LENGTH = 100

EXPECTED_PARTS_COUNT module-attribute

EXPECTED_PARTS_COUNT = 2

CommitMessageGenerator

Generates commit messages using LLMs.

Source code in src/codemap/git/commit_generator/generator.py

class CommitMessageGenerator:
	"""Generates commit messages using LLMs."""

	def __init__(
		self,
		repo_root: Path,
		llm_client: LLMClient,
		prompt_template: str,
		config_loader: ConfigLoader,
	) -> None:
		"""
		Initialize the commit message generator.

		Args:
		    repo_root: Root directory of the Git repository
		    llm_client: LLMClient instance to use
		    prompt_template: Custom prompt template to use
		    config_loader: ConfigLoader instance to use for configuration

		"""
		self.repo_root = repo_root
		self.prompt_template = prompt_template
		self._config_loader = config_loader
		self.client = llm_client

		# Add commit template to client
		self.client.set_template("commit", self.prompt_template)

		# Get max token limit from config
		llm_config = self._config_loader.get("llm", {})
		self.max_tokens = llm_config.get("max_context_tokens", 4000)

		# Flag to control whether to use the LOD-based context processing
		self.use_lod_context = llm_config.get("use_lod_context", True)

	def extract_file_info(self, chunk: DiffChunk) -> dict[str, Any]:
		"""
		Extract file information from the diff chunk.

		Args:
		    chunk: Diff chunk object to extract information from

		Returns:
		    Dictionary with information about files

		"""
		file_info = {}
		files = chunk.files
		for file in files:
			if not isinstance(file, str):
				continue  # Skip non-string file entries
			file_path = self.repo_root / file
			if not file_path.exists():
				continue
			try:
				extension = file_path.suffix.lstrip(".")
				file_info[file] = {
					"extension": extension,
					"directory": str(file_path.parent.relative_to(self.repo_root)),
				}
				path_parts = file_path.parts
				if len(path_parts) > 1:
					if "src" in path_parts:
						idx = path_parts.index("src")
						if idx + 1 < len(path_parts):
							file_info[file]["module"] = path_parts[idx + 1]
					elif "tests" in path_parts:
						file_info[file]["module"] = "tests"
			except (ValueError, IndexError, TypeError):
				continue
		return file_info

	def get_commit_convention(self) -> dict[str, Any]:
		"""Get commit convention settings from config."""
		# Use the centralized ConfigLoader to get the convention
		return self._config_loader.get_commit_convention()

	def _prepare_prompt(self, chunk: DiffChunk) -> str:
		"""
		Prepare the prompt for the LLM.

		Args:
		    chunk: Diff chunk object to prepare prompt for

		Returns:
		    Prepared prompt with diff and file information

		"""
		file_info = self.extract_file_info(chunk)
		convention = self.get_commit_convention()

		# Get the diff content
		diff_content = chunk.content

		# Use the LOD-based context processor if enabled
		if self.use_lod_context:
			logger.debug("Using LOD-based context processing")
			try:
				# Process the chunk with LOD to optimize context length
				enhanced_diff_content = process_chunks_with_lod([chunk], self.max_tokens)

				if enhanced_diff_content:
					diff_content = enhanced_diff_content
					logger.debug("LOD context processing successful")
				else:
					logger.debug("LOD processing returned empty result, using original content")
			except Exception:
				logger.exception("Error during LOD context processing")
				# Continue with the original content if LOD processing fails
		else:
			# Use the original binary file detection logic
			binary_files = []
			for file_path in chunk.files:
				if file_path in file_info:
					extension = file_info[file_path].get("extension", "").lower()
					# Common binary file extensions
					binary_extensions = {
						"png",
						"jpg",
						"jpeg",
						"gif",
						"bmp",
						"tiff",
						"ico",
						"webp",  # Images
						"mp3",
						"wav",
						"ogg",
						"flac",
						"aac",  # Audio
						"mp4",
						"avi",
						"mkv",
						"mov",
						"webm",  # Video
						"pdf",
						"doc",
						"docx",
						"xls",
						"xlsx",
						"ppt",
						"pptx",  # Documents
						"zip",
						"tar",
						"gz",
						"rar",
						"7z",  # Archives
						"exe",
						"dll",
						"so",
						"dylib",  # Binaries
						"ttf",
						"otf",
						"woff",
						"woff2",  # Fonts
						"db",
						"sqlite",
						"mdb",  # Databases
					}

					if extension in binary_extensions:
						binary_files.append(file_path)

				# For absolute paths, try to check if the file is binary
				abs_path = self.repo_root / file_path
				try:
					if abs_path.exists():
						from codemap.utils.file_utils import is_binary_file

						if is_binary_file(abs_path) and file_path not in binary_files:
							binary_files.append(file_path)
				except (OSError, PermissionError) as e:
					# If any error occurs during binary check, log it and continue
					logger.debug("Error checking if %s is binary: %s", file_path, str(e))

			# If we have binary files or no diff content, enhance the prompt
			enhanced_diff_content = diff_content
			if not diff_content or binary_files:
				# Create a specialized header for binary files
				binary_files_header = ""
				if binary_files:
					binary_files_header = "BINARY FILES DETECTED:\n"
					for binary_file in binary_files:
						extension = file_info.get(binary_file, {}).get("extension", "unknown")
						binary_files_header += f"- {binary_file} (binary {extension} file)\n"
					binary_files_header += "\n"

				# If no diff content, create a more informative message about binary files
				if not diff_content:
					file_descriptions = []
					for file_path in chunk.files:
						if file_path in binary_files:
							extension = file_info.get(file_path, {}).get("extension", "unknown")
							file_descriptions.append(f"{file_path} (binary {extension} file)")
						else:
							extension = file_info.get(file_path, {}).get("extension", "")
							file_descriptions.append(f"{file_path} ({extension} file)")

					enhanced_diff_content = (
						f"{binary_files_header}This chunk contains changes to the following files "
						f"with no visible diff content (likely binary changes):\n"
					)
					for desc in file_descriptions:
						enhanced_diff_content += f"- {desc}\n"
				else:
					# If there is diff content but also binary files, add the binary files header
					enhanced_diff_content = binary_files_header + diff_content

			diff_content = enhanced_diff_content

		# Create a context dict with default values for template variables
		context = {
			"diff": diff_content,
			"files": file_info,
			"convention": convention,
			"schema": COMMIT_MESSAGE_SCHEMA,
			"original_message": "",  # Default value for original_message
			"lint_errors": "",  # Default value for lint_errors
		}

		# Prepare and return the prompt
		return prepare_prompt(
			template=self.prompt_template,
			diff_content=diff_content,
			file_info=file_info,
			convention=convention,
			extra_context=context,  # Pass the context with default values
		)

	def format_json_to_commit_message(self, content: str) -> str:
		"""
		Format a JSON string as a conventional commit message.

		Args:
		    content: JSON content string from LLM response

		Returns:
		    Formatted commit message string

		"""

		def _raise_validation_error(message: str) -> None:
			"""Helper to raise ValueError with consistent message."""
			logger.warning("LLM response validation failed: %s", message)
			msg = message
			raise ValueError(msg)

		try:
			# Try to parse the content as JSON
			debug_content = (
				content[:MAX_DEBUG_CONTENT_LENGTH] + "..." if len(content) > MAX_DEBUG_CONTENT_LENGTH else content
			)
			logger.debug("Parsing JSON content: %s", debug_content)

			# Handle both direct JSON objects and strings containing JSON
			if not content.strip().startswith("{"):
				# Extract JSON if it's wrapped in other text
				import re

				json_match = re.search(r"({.*})", content, re.DOTALL)
				if json_match:
					content = json_match.group(1)

			message_data = json.loads(content)
			logger.debug("Parsed JSON: %s", message_data)

			# Basic Schema Validation
			if not isinstance(message_data, dict):
				_raise_validation_error("JSON response is not an object")

			if not message_data.get("type") or not message_data.get("description"):
				_raise_validation_error("Missing required fields in JSON response")

			# Extract components with validation/defaults
			commit_type = str(message_data["type"]).lower().strip()

			# Check for valid commit type (from the config)
			valid_types = self._config_loader.get_commit_convention().get("types", [])
			if valid_types and commit_type not in valid_types:
				logger.warning("Invalid commit type: %s. Valid types: %s", commit_type, valid_types)
				# Try to find a valid type as fallback
				if "feat" in valid_types:
					commit_type = "feat"
				elif "fix" in valid_types:
					commit_type = "fix"
				elif len(valid_types) > 0:
					commit_type = valid_types[0]
				logger.debug("Using fallback commit type: %s", commit_type)

			scope = message_data.get("scope")
			if scope is not None:
				scope = str(scope).lower().strip()

			description = str(message_data["description"]).lower().strip()

			# Ensure description doesn't start with another type prefix
			for valid_type in valid_types:
				if description.startswith(f"{valid_type}:"):
					# Remove the duplicate type prefix from description
					description = description.split(":", 1)[1].strip()
					logger.debug("Removed duplicate type prefix from description: %s", description)
					break

			body = message_data.get("body")
			if body is not None:
				body = str(body).strip()
			is_breaking = bool(message_data.get("breaking", False))

			# Format the header
			header = f"{commit_type}"
			if scope:
				header += f"({scope})"
			if is_breaking:
				header += "!"
			header += f": {description}"

			# Ensure compliance with commit format regex
			# The regex requires a space after the colon, and the format should be <type>(<scope>)!: <description>
			if ": " not in header:
				parts = header.split(":")
				if len(parts) == EXPECTED_PARTS_COUNT:
					header = f"{parts[0]}: {parts[1].strip()}"

			# Validation check against regex pattern
			import re

			from codemap.git.commit_linter.constants import COMMIT_REGEX

			# If header doesn't match the expected format, log and try to fix it
			if not COMMIT_REGEX.match(header):
				logger.warning("Generated header doesn't match commit format: %s", header)
				# As a fallback, recreate with a simpler format
				simple_header = f"{commit_type}"
				if scope:
					simple_header += f"({scope})"
				if is_breaking:
					simple_header += "!"
				simple_header += f": {description}"
				header = simple_header
				logger.debug("Fixed header to: %s", header)

			# Build the complete message
			message_parts = [header]

			# Add body if provided
			if body:
				message_parts.append("")  # Empty line between header and body
				message_parts.append(body)

			# Carefully filter only breaking change footers
			footers = message_data.get("footers", [])
			breaking_change_footers = []

			if isinstance(footers, list):
				breaking_change_footers = [
					footer
					for footer in footers
					if isinstance(footer, dict)
					and footer.get("token", "").upper() in ("BREAKING CHANGE", "BREAKING-CHANGE")
				]

			if breaking_change_footers:
				if not body:
					message_parts.append("")  # Empty line before footers if no body
				else:
					message_parts.append("")  # Empty line between body and footers

				for footer in breaking_change_footers:
					token = footer.get("token", "")
					value = footer.get("value", "")
					message_parts.append(f"{token}: {value}")

			message = "\n".join(message_parts)
			logger.debug("Formatted commit message: %s", message)
			return message

		except (json.JSONDecodeError, ValueError, TypeError, AttributeError) as e:
			# If parsing or validation fails, return the content as-is, but cleaned
			logger.warning("Error formatting JSON to commit message: %s. Using raw content.", str(e))
			return content.strip()

	def fallback_generation(self, chunk: DiffChunk) -> str:
		"""
		Generate a fallback commit message without LLM.

		This is used when LLM-based generation fails or is disabled.

		Args:
		    chunk: Diff chunk object to generate message for

		Returns:
		    Generated commit message

		"""
		commit_type = "chore"

		# Get files directly from the chunk object
		files = chunk.files

		# Filter only strings (defensive, though DiffChunk.files should be list[str])
		string_files = [f for f in files if isinstance(f, str)]

		for file in string_files:
			if file.startswith("tests/"):
				commit_type = "test"
				break
			if file.startswith("docs/") or file.endswith(".md"):
				commit_type = "docs"
				break

		# Get content directly from the chunk object
		content = chunk.content

		if isinstance(content, str) and ("fix" in content.lower() or "bug" in content.lower()):
			commit_type = "fix"  # Be slightly smarter about 'fix' type

		# Use chunk description if available and seems specific (not just placeholder)
		chunk_desc = chunk.description
		placeholder_descs = ["update files", "changes in", "hunk in", "new file:"]
		# Ensure chunk_desc is not None before calling lower()
		use_chunk_desc = chunk_desc and not any(p in chunk_desc.lower() for p in placeholder_descs)

		if use_chunk_desc and chunk_desc:  # Add explicit check for chunk_desc
			description = chunk_desc
			# Attempt to extract a type from the chunk description if possible
			# Ensure chunk_desc is not None before calling lower() and split()
			if chunk_desc.lower().startswith(
				("feat", "fix", "refactor", "docs", "test", "chore", "style", "perf", "ci", "build")
			):
				parts = chunk_desc.split(":", 1)
				if len(parts) > 1:
					commit_type = parts[0].split("(")[0].strip().lower()  # Extract type before scope
					description = parts[1].strip()
		else:
			# Generate description based on file count/path if no specific chunk desc
			description = "update files"  # Default
			if string_files:
				if len(string_files) == 1:
					description = f"update {string_files[0]}"
				else:
					try:
						common_dir = os.path.commonpath(string_files)
						# Make common_dir relative to repo root if possible
						try:
							common_dir_rel = os.path.relpath(common_dir, self.repo_root)
							if common_dir_rel and common_dir_rel != ".":
								description = f"update files in {common_dir_rel}"
							else:
								description = f"update {len(string_files)} files"
						except ValueError:  # Happens if paths are on different drives (unlikely in repo)
							description = f"update {len(string_files)} files"

					except (ValueError, TypeError):  # commonpath fails on empty list or mixed types
						description = f"update {len(string_files)} files"

		message = f"{commit_type}: {description}"
		logger.debug("Generated fallback message: %s", message)
		return message

	def generate_message(self, chunk: DiffChunk) -> tuple[str, bool]:
		"""
		Generate a commit message for a diff chunk.

		Args:
		    chunk: Diff chunk to generate message for

		Returns:
		    Generated message and success flag

		"""
		# Prepare prompt with chunk data
		try:
			prompt = self._prepare_prompt(chunk)
			logger.debug("Prompt prepared successfully")

			# Generate message using configured LLM provider
			message = self._call_llm_api(prompt)
			logger.debug("LLM generated message: %s", message)

			# Return generated message with success flag
			return message, True
		except (ValueError, TypeError, KeyError, LLMError):
			logger.exception("Error during LLM generation")
			# Fall back to heuristic generation
			return self.fallback_generation(chunk), False

	def _call_llm_api(self, prompt: str) -> str:
		"""
		Call the LLM API with the given prompt.

		Args:
		    prompt: Prompt to send to the LLM

		Returns:
		    Raw response content from the LLM

		Raises:
		    LLMError: If the API call fails

		"""
		# Directly use the generate_text method from the LLMClient
		return self.client.generate_text(prompt=prompt, json_schema=COMMIT_MESSAGE_SCHEMA)

	def generate_message_with_linting(
		self, chunk: DiffChunk, retry_count: int = 1, max_retries: int = 3
	) -> tuple[str, bool, bool, list[str]]:
		"""
		Generate a commit message with linting verification.

		Args:
		        chunk: The DiffChunk to generate a message for
		        retry_count: Current retry count (default: 1)
		        max_retries: Maximum number of retries for linting (default: 3)

		Returns:
		        Tuple of (message, used_llm, passed_linting, lint_messages)

		"""
		# First, generate the initial message
		initial_lint_messages: list[str] = []  # Store initial messages
		try:
			message, used_llm = self.generate_message(chunk)
			logger.debug("Generated initial message: %s", message)

			# Clean the message before linting
			message = clean_message_for_linting(message)

			# Check if the message passes linting
			is_valid, error_message = lint_commit_message(
				message, repo_root=self.repo_root, config_loader=self._config_loader
			)
			initial_lint_messages = [error_message] if error_message is not None else []
			logger.debug("Lint result: valid=%s, messages=%s", is_valid, initial_lint_messages)

			if is_valid or retry_count >= max_retries:
				# Return empty list if valid, or initial messages if max retries reached
				return message, used_llm, is_valid, [] if is_valid else initial_lint_messages

			# Prepare the diff content
			diff_content = chunk.content
			if not diff_content:
				# Check if we have binary files in the chunk
				binary_files = []
				for file_path in chunk.files:
					# First check file extension
					extension = ""
					file_info = self.extract_file_info(chunk)
					if file_path in file_info:
						extension = file_info[file_path].get("extension", "").lower()
						binary_extensions = {
							"png",
							"jpg",
							"jpeg",
							"gif",
							"bmp",
							"ico",
							"webp",
							"mp3",
							"wav",
							"mp4",
							"avi",
							"mov",
							"pdf",
							"zip",
							"tar",
							"gz",
							"exe",
							"dll",
							"so",
						}
						if extension in binary_extensions:
							binary_files.append(file_path)

					# Also try to detect binary files directly
					abs_path = self.repo_root / file_path
					try:
						if abs_path.exists():
							from codemap.utils.file_utils import is_binary_file

							if is_binary_file(abs_path) and file_path not in binary_files:
								binary_files.append(file_path)
					except (OSError, PermissionError) as e:
						# If any error occurs during binary check, log it and continue
						logger.debug("Error checking if %s is binary: %s", file_path, str(e))

				if binary_files:
					# Create a more descriptive message for binary files
					diff_content = "Binary files detected in this chunk:\n"
					for binary_file in binary_files:
						diff_content += f"- {binary_file}\n"
				else:
					# Generic fallback for empty diff with no binary files detected
					diff_content = "Empty diff (likely modified binary files)"

			logger.info("Regenerating message with linting feedback (attempt %d/%d)", retry_count, max_retries)

			try:
				# Prepare the enhanced prompt for regeneration
				lint_template = get_lint_prompt_template()
				enhanced_prompt = prepare_lint_prompt(
					template=lint_template,
					file_info=self.extract_file_info(chunk),  # Use self
					convention=self.get_commit_convention(),  # Use self
					lint_messages=initial_lint_messages,  # Use initial messages for feedback
					original_message=message,  # Pass the original message that failed linting
				)

				# Generate message with the enhanced prompt
				regenerated_message = self._call_llm_api(enhanced_prompt)
				logger.debug("Regenerated message (RAW LLM output): %s", regenerated_message)

				# Format from JSON to commit message format
				regenerated_message = self.format_json_to_commit_message(regenerated_message)
				logger.debug("Formatted message: %s", regenerated_message)

				# Clean and recheck linting
				cleaned_message = clean_message_for_linting(regenerated_message)
				logger.debug("Cleaned message for linting: %s", cleaned_message)

				# Check if the message passes linting
				final_is_valid, error_message = lint_commit_message(
					cleaned_message, repo_root=self.repo_root, config_loader=self._config_loader
				)
				final_lint_messages = [error_message] if error_message is not None else []
				logger.debug("Regenerated lint result: valid=%s, messages=%s", final_is_valid, final_lint_messages)

				# Return final result and messages (empty if valid)
				return cleaned_message, True, final_is_valid, [] if final_is_valid else final_lint_messages
			except (ValueError, TypeError, KeyError, LLMError, json.JSONDecodeError):
				# If regeneration fails, log it and return the original message and its lint errors
				logger.exception("Error during message regeneration")
				return message, used_llm, False, initial_lint_messages  # Return original message and errors
		except (ValueError, TypeError, KeyError, LLMError, json.JSONDecodeError):
			# If generation fails completely, use a fallback (fallback doesn't lint, so return True, empty messages)
			logger.exception("Error during message generation")
			message = self.fallback_generation(chunk)
			return message, False, True, []  # Fallback assumes valid, no lint messages

	def get_config_loader(self) -> ConfigLoader:
		"""
		Get the ConfigLoader instance used by this generator.

		Returns:
		    ConfigLoader instance

		"""
		return self._config_loader

__init__

__init__(
	repo_root: Path,
	llm_client: LLMClient,
	prompt_template: str,
	config_loader: ConfigLoader,
) -> None

Initialize the commit message generator.

Parameters:

Name	Type	Description	Default
repo_root	Path	Root directory of the Git repository	required
llm_client	LLMClient	LLMClient instance to use	required
prompt_template	str	Custom prompt template to use	required
config_loader	ConfigLoader	ConfigLoader instance to use for configuration	required

Source code in src/codemap/git/commit_generator/generator.py

def __init__(
	self,
	repo_root: Path,
	llm_client: LLMClient,
	prompt_template: str,
	config_loader: ConfigLoader,
) -> None:
	"""
	Initialize the commit message generator.

	Args:
	    repo_root: Root directory of the Git repository
	    llm_client: LLMClient instance to use
	    prompt_template: Custom prompt template to use
	    config_loader: ConfigLoader instance to use for configuration

	"""
	self.repo_root = repo_root
	self.prompt_template = prompt_template
	self._config_loader = config_loader
	self.client = llm_client

	# Add commit template to client
	self.client.set_template("commit", self.prompt_template)

	# Get max token limit from config
	llm_config = self._config_loader.get("llm", {})
	self.max_tokens = llm_config.get("max_context_tokens", 4000)

	# Flag to control whether to use the LOD-based context processing
	self.use_lod_context = llm_config.get("use_lod_context", True)

repo_root instance-attribute

repo_root = repo_root

prompt_template instance-attribute

prompt_template = prompt_template

client instance-attribute

client = llm_client

max_tokens instance-attribute

max_tokens = get('max_context_tokens', 4000)

use_lod_context instance-attribute

use_lod_context = get('use_lod_context', True)

extract_file_info

extract_file_info(chunk: DiffChunk) -> dict[str, Any]

Extract file information from the diff chunk.

Parameters:

Name	Type	Description	Default
chunk	DiffChunk	Diff chunk object to extract information from	required

Returns:

Type	Description
dict[str, Any]	Dictionary with information about files

Source code in src/codemap/git/commit_generator/generator.py

def extract_file_info(self, chunk: DiffChunk) -> dict[str, Any]:
	"""
	Extract file information from the diff chunk.

	Args:
	    chunk: Diff chunk object to extract information from

	Returns:
	    Dictionary with information about files

	"""
	file_info = {}
	files = chunk.files
	for file in files:
		if not isinstance(file, str):
			continue  # Skip non-string file entries
		file_path = self.repo_root / file
		if not file_path.exists():
			continue
		try:
			extension = file_path.suffix.lstrip(".")
			file_info[file] = {
				"extension": extension,
				"directory": str(file_path.parent.relative_to(self.repo_root)),
			}
			path_parts = file_path.parts
			if len(path_parts) > 1:
				if "src" in path_parts:
					idx = path_parts.index("src")
					if idx + 1 < len(path_parts):
						file_info[file]["module"] = path_parts[idx + 1]
				elif "tests" in path_parts:
					file_info[file]["module"] = "tests"
		except (ValueError, IndexError, TypeError):
			continue
	return file_info

get_commit_convention

get_commit_convention() -> dict[str, Any]

Get commit convention settings from config.

Source code in src/codemap/git/commit_generator/generator.py

def get_commit_convention(self) -> dict[str, Any]:
	"""Get commit convention settings from config."""
	# Use the centralized ConfigLoader to get the convention
	return self._config_loader.get_commit_convention()

format_json_to_commit_message

format_json_to_commit_message(content: str) -> str

Format a JSON string as a conventional commit message.

Parameters:

Name	Type	Description	Default
content	str	JSON content string from LLM response	required

Returns:

Type	Description
str	Formatted commit message string

Source code in src/codemap/git/commit_generator/generator.py

def format_json_to_commit_message(self, content: str) -> str:
	"""
	Format a JSON string as a conventional commit message.

	Args:
	    content: JSON content string from LLM response

	Returns:
	    Formatted commit message string

	"""

	def _raise_validation_error(message: str) -> None:
		"""Helper to raise ValueError with consistent message."""
		logger.warning("LLM response validation failed: %s", message)
		msg = message
		raise ValueError(msg)

	try:
		# Try to parse the content as JSON
		debug_content = (
			content[:MAX_DEBUG_CONTENT_LENGTH] + "..." if len(content) > MAX_DEBUG_CONTENT_LENGTH else content
		)
		logger.debug("Parsing JSON content: %s", debug_content)

		# Handle both direct JSON objects and strings containing JSON
		if not content.strip().startswith("{"):
			# Extract JSON if it's wrapped in other text
			import re

			json_match = re.search(r"({.*})", content, re.DOTALL)
			if json_match:
				content = json_match.group(1)

		message_data = json.loads(content)
		logger.debug("Parsed JSON: %s", message_data)

		# Basic Schema Validation
		if not isinstance(message_data, dict):
			_raise_validation_error("JSON response is not an object")

		if not message_data.get("type") or not message_data.get("description"):
			_raise_validation_error("Missing required fields in JSON response")

		# Extract components with validation/defaults
		commit_type = str(message_data["type"]).lower().strip()

		# Check for valid commit type (from the config)
		valid_types = self._config_loader.get_commit_convention().get("types", [])
		if valid_types and commit_type not in valid_types:
			logger.warning("Invalid commit type: %s. Valid types: %s", commit_type, valid_types)
			# Try to find a valid type as fallback
			if "feat" in valid_types:
				commit_type = "feat"
			elif "fix" in valid_types:
				commit_type = "fix"
			elif len(valid_types) > 0:
				commit_type = valid_types[0]
			logger.debug("Using fallback commit type: %s", commit_type)

		scope = message_data.get("scope")
		if scope is not None:
			scope = str(scope).lower().strip()

		description = str(message_data["description"]).lower().strip()

		# Ensure description doesn't start with another type prefix
		for valid_type in valid_types:
			if description.startswith(f"{valid_type}:"):
				# Remove the duplicate type prefix from description
				description = description.split(":", 1)[1].strip()
				logger.debug("Removed duplicate type prefix from description: %s", description)
				break

		body = message_data.get("body")
		if body is not None:
			body = str(body).strip()
		is_breaking = bool(message_data.get("breaking", False))

		# Format the header
		header = f"{commit_type}"
		if scope:
			header += f"({scope})"
		if is_breaking:
			header += "!"
		header += f": {description}"

		# Ensure compliance with commit format regex
		# The regex requires a space after the colon, and the format should be <type>(<scope>)!: <description>
		if ": " not in header:
			parts = header.split(":")
			if len(parts) == EXPECTED_PARTS_COUNT:
				header = f"{parts[0]}: {parts[1].strip()}"

		# Validation check against regex pattern
		import re

		from codemap.git.commit_linter.constants import COMMIT_REGEX

		# If header doesn't match the expected format, log and try to fix it
		if not COMMIT_REGEX.match(header):
			logger.warning("Generated header doesn't match commit format: %s", header)
			# As a fallback, recreate with a simpler format
			simple_header = f"{commit_type}"
			if scope:
				simple_header += f"({scope})"
			if is_breaking:
				simple_header += "!"
			simple_header += f": {description}"
			header = simple_header
			logger.debug("Fixed header to: %s", header)

		# Build the complete message
		message_parts = [header]

		# Add body if provided
		if body:
			message_parts.append("")  # Empty line between header and body
			message_parts.append(body)

		# Carefully filter only breaking change footers
		footers = message_data.get("footers", [])
		breaking_change_footers = []

		if isinstance(footers, list):
			breaking_change_footers = [
				footer
				for footer in footers
				if isinstance(footer, dict)
				and footer.get("token", "").upper() in ("BREAKING CHANGE", "BREAKING-CHANGE")
			]

		if breaking_change_footers:
			if not body:
				message_parts.append("")  # Empty line before footers if no body
			else:
				message_parts.append("")  # Empty line between body and footers

			for footer in breaking_change_footers:
				token = footer.get("token", "")
				value = footer.get("value", "")
				message_parts.append(f"{token}: {value}")

		message = "\n".join(message_parts)
		logger.debug("Formatted commit message: %s", message)
		return message

	except (json.JSONDecodeError, ValueError, TypeError, AttributeError) as e:
		# If parsing or validation fails, return the content as-is, but cleaned
		logger.warning("Error formatting JSON to commit message: %s. Using raw content.", str(e))
		return content.strip()

fallback_generation

fallback_generation(chunk: DiffChunk) -> str

Generate a fallback commit message without LLM.

This is used when LLM-based generation fails or is disabled.

Parameters:

Name	Type	Description	Default
chunk	DiffChunk	Diff chunk object to generate message for	required

Returns:

Type	Description
str	Generated commit message

Source code in src/codemap/git/commit_generator/generator.py

def fallback_generation(self, chunk: DiffChunk) -> str:
	"""
	Generate a fallback commit message without LLM.

	This is used when LLM-based generation fails or is disabled.

	Args:
	    chunk: Diff chunk object to generate message for

	Returns:
	    Generated commit message

	"""
	commit_type = "chore"

	# Get files directly from the chunk object
	files = chunk.files

	# Filter only strings (defensive, though DiffChunk.files should be list[str])
	string_files = [f for f in files if isinstance(f, str)]

	for file in string_files:
		if file.startswith("tests/"):
			commit_type = "test"
			break
		if file.startswith("docs/") or file.endswith(".md"):
			commit_type = "docs"
			break

	# Get content directly from the chunk object
	content = chunk.content

	if isinstance(content, str) and ("fix" in content.lower() or "bug" in content.lower()):
		commit_type = "fix"  # Be slightly smarter about 'fix' type

	# Use chunk description if available and seems specific (not just placeholder)
	chunk_desc = chunk.description
	placeholder_descs = ["update files", "changes in", "hunk in", "new file:"]
	# Ensure chunk_desc is not None before calling lower()
	use_chunk_desc = chunk_desc and not any(p in chunk_desc.lower() for p in placeholder_descs)

	if use_chunk_desc and chunk_desc:  # Add explicit check for chunk_desc
		description = chunk_desc
		# Attempt to extract a type from the chunk description if possible
		# Ensure chunk_desc is not None before calling lower() and split()
		if chunk_desc.lower().startswith(
			("feat", "fix", "refactor", "docs", "test", "chore", "style", "perf", "ci", "build")
		):
			parts = chunk_desc.split(":", 1)
			if len(parts) > 1:
				commit_type = parts[0].split("(")[0].strip().lower()  # Extract type before scope
				description = parts[1].strip()
	else:
		# Generate description based on file count/path if no specific chunk desc
		description = "update files"  # Default
		if string_files:
			if len(string_files) == 1:
				description = f"update {string_files[0]}"
			else:
				try:
					common_dir = os.path.commonpath(string_files)
					# Make common_dir relative to repo root if possible
					try:
						common_dir_rel = os.path.relpath(common_dir, self.repo_root)
						if common_dir_rel and common_dir_rel != ".":
							description = f"update files in {common_dir_rel}"
						else:
							description = f"update {len(string_files)} files"
					except ValueError:  # Happens if paths are on different drives (unlikely in repo)
						description = f"update {len(string_files)} files"

				except (ValueError, TypeError):  # commonpath fails on empty list or mixed types
					description = f"update {len(string_files)} files"

	message = f"{commit_type}: {description}"
	logger.debug("Generated fallback message: %s", message)
	return message

generate_message

generate_message(chunk: DiffChunk) -> tuple[str, bool]

Generate a commit message for a diff chunk.

Parameters:

Name	Type	Description	Default
chunk	DiffChunk	Diff chunk to generate message for	required

Returns:

Type	Description
tuple[str, bool]	Generated message and success flag

Source code in src/codemap/git/commit_generator/generator.py

def generate_message(self, chunk: DiffChunk) -> tuple[str, bool]:
	"""
	Generate a commit message for a diff chunk.

	Args:
	    chunk: Diff chunk to generate message for

	Returns:
	    Generated message and success flag

	"""
	# Prepare prompt with chunk data
	try:
		prompt = self._prepare_prompt(chunk)
		logger.debug("Prompt prepared successfully")

		# Generate message using configured LLM provider
		message = self._call_llm_api(prompt)
		logger.debug("LLM generated message: %s", message)

		# Return generated message with success flag
		return message, True
	except (ValueError, TypeError, KeyError, LLMError):
		logger.exception("Error during LLM generation")
		# Fall back to heuristic generation
		return self.fallback_generation(chunk), False

generate_message_with_linting

generate_message_with_linting(
	chunk: DiffChunk,
	retry_count: int = 1,
	max_retries: int = 3,
) -> tuple[str, bool, bool, list[str]]

Generate a commit message with linting verification.

Parameters:

Name	Type	Description	Default
chunk	DiffChunk	The DiffChunk to generate a message for	required
retry_count	int	Current retry count (default: 1)	1
max_retries	int	Maximum number of retries for linting (default: 3)	3

Returns:

Type	Description
tuple[str, bool, bool, list[str]]	Tuple of (message, used_llm, passed_linting, lint_messages)

Source code in src/codemap/git/commit_generator/generator.py

def generate_message_with_linting(
	self, chunk: DiffChunk, retry_count: int = 1, max_retries: int = 3
) -> tuple[str, bool, bool, list[str]]:
	"""
	Generate a commit message with linting verification.

	Args:
	        chunk: The DiffChunk to generate a message for
	        retry_count: Current retry count (default: 1)
	        max_retries: Maximum number of retries for linting (default: 3)

	Returns:
	        Tuple of (message, used_llm, passed_linting, lint_messages)

	"""
	# First, generate the initial message
	initial_lint_messages: list[str] = []  # Store initial messages
	try:
		message, used_llm = self.generate_message(chunk)
		logger.debug("Generated initial message: %s", message)

		# Clean the message before linting
		message = clean_message_for_linting(message)

		# Check if the message passes linting
		is_valid, error_message = lint_commit_message(
			message, repo_root=self.repo_root, config_loader=self._config_loader
		)
		initial_lint_messages = [error_message] if error_message is not None else []
		logger.debug("Lint result: valid=%s, messages=%s", is_valid, initial_lint_messages)

		if is_valid or retry_count >= max_retries:
			# Return empty list if valid, or initial messages if max retries reached
			return message, used_llm, is_valid, [] if is_valid else initial_lint_messages

		# Prepare the diff content
		diff_content = chunk.content
		if not diff_content:
			# Check if we have binary files in the chunk
			binary_files = []
			for file_path in chunk.files:
				# First check file extension
				extension = ""
				file_info = self.extract_file_info(chunk)
				if file_path in file_info:
					extension = file_info[file_path].get("extension", "").lower()
					binary_extensions = {
						"png",
						"jpg",
						"jpeg",
						"gif",
						"bmp",
						"ico",
						"webp",
						"mp3",
						"wav",
						"mp4",
						"avi",
						"mov",
						"pdf",
						"zip",
						"tar",
						"gz",
						"exe",
						"dll",
						"so",
					}
					if extension in binary_extensions:
						binary_files.append(file_path)

				# Also try to detect binary files directly
				abs_path = self.repo_root / file_path
				try:
					if abs_path.exists():
						from codemap.utils.file_utils import is_binary_file

						if is_binary_file(abs_path) and file_path not in binary_files:
							binary_files.append(file_path)
				except (OSError, PermissionError) as e:
					# If any error occurs during binary check, log it and continue
					logger.debug("Error checking if %s is binary: %s", file_path, str(e))

			if binary_files:
				# Create a more descriptive message for binary files
				diff_content = "Binary files detected in this chunk:\n"
				for binary_file in binary_files:
					diff_content += f"- {binary_file}\n"
			else:
				# Generic fallback for empty diff with no binary files detected
				diff_content = "Empty diff (likely modified binary files)"

		logger.info("Regenerating message with linting feedback (attempt %d/%d)", retry_count, max_retries)

		try:
			# Prepare the enhanced prompt for regeneration
			lint_template = get_lint_prompt_template()
			enhanced_prompt = prepare_lint_prompt(
				template=lint_template,
				file_info=self.extract_file_info(chunk),  # Use self
				convention=self.get_commit_convention(),  # Use self
				lint_messages=initial_lint_messages,  # Use initial messages for feedback
				original_message=message,  # Pass the original message that failed linting
			)

			# Generate message with the enhanced prompt
			regenerated_message = self._call_llm_api(enhanced_prompt)
			logger.debug("Regenerated message (RAW LLM output): %s", regenerated_message)

			# Format from JSON to commit message format
			regenerated_message = self.format_json_to_commit_message(regenerated_message)
			logger.debug("Formatted message: %s", regenerated_message)

			# Clean and recheck linting
			cleaned_message = clean_message_for_linting(regenerated_message)
			logger.debug("Cleaned message for linting: %s", cleaned_message)

			# Check if the message passes linting
			final_is_valid, error_message = lint_commit_message(
				cleaned_message, repo_root=self.repo_root, config_loader=self._config_loader
			)
			final_lint_messages = [error_message] if error_message is not None else []
			logger.debug("Regenerated lint result: valid=%s, messages=%s", final_is_valid, final_lint_messages)

			# Return final result and messages (empty if valid)
			return cleaned_message, True, final_is_valid, [] if final_is_valid else final_lint_messages
		except (ValueError, TypeError, KeyError, LLMError, json.JSONDecodeError):
			# If regeneration fails, log it and return the original message and its lint errors
			logger.exception("Error during message regeneration")
			return message, used_llm, False, initial_lint_messages  # Return original message and errors
	except (ValueError, TypeError, KeyError, LLMError, json.JSONDecodeError):
		# If generation fails completely, use a fallback (fallback doesn't lint, so return True, empty messages)
		logger.exception("Error during message generation")
		message = self.fallback_generation(chunk)
		return message, False, True, []  # Fallback assumes valid, no lint messages

get_config_loader

get_config_loader() -> ConfigLoader

Get the ConfigLoader instance used by this generator.

Returns:

Type	Description
ConfigLoader	ConfigLoader instance

Source code in src/codemap/git/commit_generator/generator.py

def get_config_loader(self) -> ConfigLoader:
	"""
	Get the ConfigLoader instance used by this generator.

	Returns:
	    ConfigLoader instance

	"""
	return self._config_loader

View Source Code